API Reference

About

Wpay

Contact

Documentation Hub

Overview

Google Pay

Grow your payment capabilities with code.

How scalable payments flow

Digital wallets

Digital wallets in Embed

Events

Embed events

Locales

Embed localization

Theming

Embed Theming

Options

Embed options

In-app browsers

In-app browsers with Embed

Use Secure Fields to collect the CVV for cards previously stored.

Stored cards

Secure Fields with stored cards

Each field can be customized to match your brand using the `styles` property
when adding the field.

Secure Fields Theming

Secure Fields events

Enable Click to Pay for use with Secure Fields

Click to Pay

Click to Pay with Secure Fields

Secure Fields and 3DS

PayPal

PayPal via the API

Vault token import

Import file

Token import file creation

Upload tokens

Token import file upload

Buyers & payment methods

Creating buyers & payment methods on import

Vault Forwarding

Enable endpoint

Enable a Vault Forwarding endpoint

Forward to endpoint

Forward card data to API endpoint

Securing user access with fine-grained controls

Roles & Permissions

Roles

User roles

Additional permissions

Additional user permissions

3-D Secure

Setup

Setup 3-D Secure

Embed

3-D Secure in Embed

Hosted via API

Hosted 3-D Secure

External 3DS server

External 3-D Secure server

Testing

3-D Secure Testing

Account Updater

Integration

Integrating an account updater

Anti-fraud

Anti-fraud setup

Fingerprints

Automatic anti-fraud device fingerprinting

Reviews

Anti-fraud reviews

Attributes

Anti-fraud Specific Attributes

Simulator

Apple Pay

Web with Embed

Apple Pay on web with Embed

Web without Embed

Apple Pay on web without Embed

iOS with SDK

Apple Pay on iOS with the SDK

iOS without SDK

Apple Pay on iOS without the SDK

Gift Cards

Connections

Google Pay on web with Embed

Google Pay on web without Embed

Android with SDK

Google Pay on Android with the SDK

Android without SDK

Google Pay on Android without the SDK

Using scheme tokens with payment orchestration

Network tokens

How to use scheme tokens with or without payment orchestration

Implementation

Network token implementation

Managing the full lifecycle of network tokens

Lifecycle

Network token lifecycle management

Network Token Testing

Common scenarios

In Embed

Recurring transactions with Embed

A unique hash for every card in our vault

Card fingerprints

A unique ID for the account behind the card

Payment account references

Introduction

Webhooks

Payload

Technical considerations

A list of best practices for integrating Gr4vy into your checkout.

Best practice

API authentication basics and best practices.

Authentication

Sandbox and Production environments within an instance.

Environments

Best practices on handling errors and other exceptions.

Errors

Error handling

Best practices on handling retries in an idempotent way.

Idempotent Requests

Best practices on handling the original IP address for a transaction.

IP Address Forwarding

Best practices on handling pagination in the API.

Pagination

Rate limiting

Lists all transactions for an account. Sorted by last updated at.

List transactions

Attempts to create an authorization for a payment method. In some cases it is
not possible to create the authorization without redirecting the user for
their authorization. In these cases the status is set to
indicate buyer approval is pending and an approval URL is returned.

Duplicated gift card numbers are not supported. This includes both stored gift
cards, as well as those directly provided via the request.


New transaction

Get transaction

Captures a previously authorized transaction.

Capture transaction

Voids a transaction.

If the transaction was not yet successfully authorized, or was already
captured, the void will not be processed. Captured transactions can be
refunded instead.

Voiding zero-amount authorized transactions is not supported.

Once voided, the status of the transaction will be either `authorization_voided`,
`authorization_void_pending`, or if the void fails the original status will remain.

Void transaction

Get a list of events related to processing a transaction.

List events for transaction

List buyers

Adds a buyer, allowing for payment methods and transactions to be associated
to this buyer.


New buyer

Get buyer

Update buyer

Deletes a buyer record. Any associated stored payment methods will remain
in the system but no longer associated to the buyer.

Delete buyer

New checkout session

Gets details about a current Checkout Session.

Get checkout session

Update checkout session

Delete checkout session

Updates the Secure Fields of the Checkout Session.

Update fields for checkout session

Returns a list of available payment method options for the combination of
amount, currency, country and metadata.

If the amount is zero, payment options which do not support zero amounts,
will be omitted in the response.

Checkout flow rules are used to limit these result.

List payment options

Returns a list of available payment method options for the combination of
amount, currency, country, metadata and list of cart items.

If the amount is zero, payment options which do not support zero amounts,
will be omitted in the response.

Checkout flow rules are used to limit these result.

List payment options with POST

Lists all refunds associated with a certain transaction.

List refunds

Refunds a transaction, fully or partially.

If the transaction was not yet successfully captured, the
refund will not be processed. Authorized transactions can be
voided instead.

Refund transaction

Refunds a transaction fully across all instruments.

Refund all instruments

Refund all instruments in a transaction

Get refund

Creates a session for a payment service. This endpoint directly
passes the request through to the relevant payment service for processing,
and so the schema will differ based on the service used.

If the downstream service returns an error, this API will return a successful response
with the status code in the response.

Get session

Create a session for a payment service

Creates a session for a payment service. This endpoint directly
passes the request through to the relevant payment service for processing,
and so the schema will differ based on the service used.


If the downstream service returns an error, this API will return a successful response
with the status code in the response.

Get session by ID

Create a session for a payment service by ID

Returns a list of all available card scheme definitions.

List card scheme definitions

Initiates a new session with Apple Pay. This can be used when implementing
Apple Pay without our SDK.

This endpoint returns an opaque object that can be directly passed to the
Apple Pay SDK. The format of this object may change when the format returned by
the Apple Pay API changes.

New Apple Pay session

Initiates a new session with Google Pay. This can be used when implementing
Google Pay without our SDK.

New Google Pay session

Returns digital payment application ID & name for use with Click to Pay.

New Click to Pay session

Returns a list of all stored, not-expired gift cards and
their balances for a buyer in a summarized format. Any
expired or empty gift cards will be automatically filtered
out and removed from the list of returned cards.

If we were not able to fetch the latest balance then all
stored gift cards are returned.

List gift cards buyer

List gift cards

Verify gift cards are enrolled and fetch their balances.

This verifies a list of gift cards are enrolled for your gift card programme,
if this feature is available via your gift card service. It then also fetches each card's
current balance.

Duplicated gift card numbers are not supported. This includes both stored gift
cards, as well as those directly provided via the request.

Verify & get balance

Verify and get gift card balances

Stores a gift card.

Vaulting a gift card stores and validate it against the active gift card
service.

It is only possible to store a gift card against a buyer if the same card is
not already stored on the buyer and the gift card has not expired yet.

Buyers by default can only have a maximum limit of 10 gift cards stored against
them. Please contact our team to change this limit. To clear out any expired or
empty gift cards, you can call the `GET /buyers/gift-cards` endpoint which will
automatically archive any of those cards and allow new cards to be stored.


Store gift card

Get gift card

Delete gift card

Returns a list of stored payment methods for a buyer in a summarized format.
Only payment methods that are compatible with at least one active payment
service in that region are shown.

List payment methods for buyer

Returns a list of stored payment methods.

List payment methods

Stores and vaults a new payment method.

Vaulting a card only stores its information but doesn't validate it against any
PSP, so ephemeral data like the security code, often referred to as the CVV or
CVD, won't be used. In order to validate the card data, a CIT (Customer Initiated
Transaction) must be done, even if it's a zero-value one.


New payment method

Gets the details for a stored payment method.

Get payment method

Delete payment method

Returns a list of all available payment method definitions.

List payment method definitions

Creates an Account Updater job.

A request is submitted to a third-party service, containing inquiries for a given
set of payment methods. The job is not processed right away, but once created, it
will store new card details automatically, if there are, when results are ready.

A payment method is considered for the job if the following conditions are met:
* It exists.
* It's in a valid state: `status` is either `succeeded` or `processing`.
* It corresponds to a card: `method` is `card`.
* Its scheme is supported: `scheme` is `amex`, `discover`, `mastercard` or `visa`.
* It doesn't have an in-progress inquiry already.

The endpoint works in a best-efforts basis and it doesn't return any error when a payment
method doesn't qualify for an inquiry. To determine what payment methods were considered
for the job, an `inquiries` field, returned in the response body, contains the submitted
inquiries. If none of the payment methods qualified for an inquiry, the job is not created
and a `204 No Content` status code is returned.

	Using SDK (Embed)	Without SDK
Google Developer account required?	No	No
Customization & Theming?	Limited	Full
Integrated with Checkout Flow?	Yes	Optional

	Using SDK	Without SDK
Google Developer account required?	No	No
Customization & Theming?	Limited	Full
Integrated with Checkout Flow?	Yes	Optional

Getting Started

Payments

Cloud Vault

Dashboard

Features

API

Google Pay

Web (Embed)

Mobile (Android)