API Reference

About

Wpay

Contact

Documentation Hub

Get payout

The country for the address in ISO 3166 format.

The house number or name for the address. Not all payment
services use this field but some do.

The optional name of the company or organisation to add
to the address.

The postal code or zip code for the address.

The state, county, or province for the address.

The code of state, county, or province for the address in
ISO 3166-2 format.

Address

The first name(s) or given name of the buyer.

The last name, or family name, of the buyer.

The phone number of the buyer. This number is formatted according to the
[E164 number standard](https://www.twilio.com/docs/glossary/what-e164).

The tax information associated with the billing details.

The type of this resource. Is always `billing-details`.

Billing details

Snapshot of a buyer, as used when embedded inside other
resources.

The billing details associated with the buyer, which include the
address and tax ID.

A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.

An external identifier that can be used to match the buyer against your own records.

The type of this resource. Is always `buyer`.

Buyer (Snapshot)

Additional detail about the part of a request body that caused an issue.

The location where the error caused an issue.

A human readable message for this error detail.

The exact item for which the validation did not succeed. This is a JSON
pointer for request bodies, while for query, path, and header parameters
it is the name of the parameter.

A unique identifier for the type of error that occurred.

Error details

Unique value which identifies a merchant for processing transactions, also known as a MID.

Merchant classification for the type of goods or services it provides.

The phone number for the merchant which should be formatted according to the
[E164 number standard](https://www.twilio.com/docs/glossary/what-e164).

Value to explain charges or payments on bank statements.

The type of this resource. Is always `merchant`.

Merchant

Snapshot of a payment method, as used when embedded inside other
resources.

The browser target that an approval URL must be opened in. If `any` or `null`, then there is no specific requirement.

The optional URL that the buyer needs to be redirected to to further authorize their payment.

The 2-letter ISO code of the country this payment method can
be used for. If this value is `null` the payment method may be
used in multiple countries.

The ISO-4217 currency code that this payment method can be
used for. If this value is `null` the payment method may be
used for multiple currencies.

The expiration date for this payment method. This is mostly used by cards
where the card might have an expiration date.

An external identifier that can be used to match the payment method
against your own records.

The unique hash derived from the payment method identifier (e.g. card number).

A label for the payment method. This can be the last 4 digits for a card,
or the email address for an alternative payment method.

The date and time when this card was last replaced.

When the Account Updater determines that new card details are available, existing details are not
changed immediately. There are three scenarios in which the actual replacement occurs:

1. When this card has expired.
2. When only the expiration date changed.
3. When a transaction using this card is declined with any of the following codes:
    * `canceled_payment_method`
    * `expired_payment_method`
    * `unavailable_payment_method`
    * `unknown_payment_method`

When the replacement is applied, this field is updated.
For non-card payment methods, the value of this field is always set to `null`.

The payment account reference (PAR) returned by the card scheme. This is a unique
reference to the underlying account that has been used to fund this payment method.
This value will be unique if the same underlying account was used, regardless of
the actual payment method used. For example, a network token or an Apple Pay device
token will return the same PAR when possible.

The uniqueness of this value will depend on the card scheme, please refer to their documentation
for further details. The availability of the PAR in our API depends on the availability
of its value in the API of the payment service used for the transaction.

An additional label used to differentiate different sub-types of a payment
method. Most notably this can include the type of card used in a
transaction. This field is `null` for the non-card payment methods.
This represents the card scheme sent to the connector and it could be different from the
actual card scheme that is being used by the PSP to process the transaction
in the following situations: 1. `use_additional_scheme` transformation is used
with the `PAN` instrument but we already have a PSP token for the card.
2. `use_additional_scheme` transformation is used but PSP has fallen back to the
main card scheme internally.

Payment method (Snapshot)

The first 6 digits of the full card number (the BIN).

The type of card, one of `credit`, `debit` or `prepaid`.

Card

The payment method that this services handles.

The ID of the payment service definition used to create this service.


A payment service

The tax ID information associated to a buyer.

Tax ID

bearerAuth

Payout

Unauthorized Error

Not Found Error

Grow your payment capabilities with code.

Overview

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 Forward

Enable endpoint

Enable a Vault Forward endpoint

Forward to endpoint

Vault 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

Manual updates

Manual account updates

Scheduled updates

Scheduled account updates

Anti-fraud

Anti-fraud setup

Fingerprints

Automatic anti-fraud device fingerprinting

Reviews

Anti-fraud reviews

Attributes

Anti-fraud Specific Attributes

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

Decrypted tokens

Decrypted Apple Pay tokens

Gift Cards

Simulator

Gift card simulator

Connections

Google Pay

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

Decrypted Google Pay tokens

Create transactions without a creating a buyer first

Guest checkout

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

Pass through

Network token pass through

Introduction

Payouts

Push payments

Push payments and Embed

Recurring payments

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

Webhooks

Payload

Webhook payload

Webhook events

Technical considerations

Technical webhook 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.

Payments

Instruments

Vault

Connections

Dashboard

Errors

Get payout

Authorizations

Path Parameters

Response