POST
/
payment-options
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "locale": "en-US",
  "currency": "USD",
  "country": "US",
  "metadata": {
    "key": "value"
  },
  "cart_items": [
    {
      "name": "GoPro HERO9 Camcorder",
      "quantity": 1,
      "unit_amount": 37999,
      "discount_amount": 0,
      "tax_amount": 0,
      "external_identifier": "item-789123",
      "sku": "sku-789123",
      "product_url": "https://example.com/items/gopro",
      "image_url": "https://example.com/images/items/gopro.png",
      "categories": [
        "<string>"
      ],
      "product_type": "physical"
    }
  ]
}'
{
  "items": [
    {
      "type": "payment-option",
      "method": "card",
      "icon_url": "https://cdn.gr4vy.app/card.svg",
      "mode": "card",
      "label": "Pay by Card",
      "can_store_payment_method": true,
      "can_delay_capture": true,
      "context": {
        "gateway": "<string>",
        "gateway_merchant_id": "<string>",
        "merchant_name": "<string>",
        "supported_schemes": [
          "<string>"
        ],
        "approval_ui": {
          "height": "300px",
          "width": "300px"
        },
        "required_fields": {
          "first_name": true,
          "last_name": true,
          "email_address": true,
          "phone_number": true,
          "address": {
            "city": true,
            "country": true,
            "postal_code": true,
            "state": true,
            "house_number_or_name": true,
            "line1": true
          },
          "tax_id": true
        }
      }
    }
  ]
}

This endpoint requires the payment-options.read or embed scope.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

A request to get list of payment options.

​
amount
integer | null

The monetary amount to create an authorization for, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99.

If the intent is set to capture, an amount greater than zero must be supplied.

Example:

1299

​
locale
string | null
default:en

An ISO 639-1 Language Code and optional ISO 3166 Country Code. This locale determines the language for the labels returned for every payment option.

Example:

"en-US"

​
currency
string | null

A supported ISO-4217 currency code.

For redirect requests, this value must match the one specified for currency in payment_method.

Example:

"USD"

​
country
string | null

Filters the results to only the items which support this country code. A country is formatted as 2-letter ISO country code.

Example:

"US"

​
metadata
object | null

Used by the Flow engine to filter available options based on various client-defined parameters. If present, this must be a string representing a valid JSON dictionary.

Example:
{ "key": "value" }
​
cart_items
object[] | null

An array of cart items that represents the line items of a transaction.

A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.

If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:

(unit_amount * quantity) - discount_amount + tax_amount

It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.

Response

200
application/json
Returns a list of available payment options for the given query parameters.

A list of payment options.

​
items
object[]

An available payment option for a locale.

Was this page helpful?

List payment optionsList payouts