POST

/payment-services

curl --request POST \
  --url https://api.sandbox.{gr4vy_id}.gr4vy.app/payment-services \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "accepted_countries": [
    "US",
    "GB",
    "DE"
  ],
  "accepted_currencies": [
    "EUR",
    "USD",
    "GBP"
  ],
  "display_name": "Stripe (Main)",
  "fields": [
    {
      "key": "private_key",
      "value": "sk_test_26PHem9AhJZvU623DfE1x4sd"
    }
  ],
  "payment_service_definition_id": "stripe-card"
}'
{
  "status": "201",
  "example": {
    "accepted_countries": [
      "DE"
    ],
    "accepted_currencies": [
      "EUR"
    ],
    "display_name": "Stripe",
    "id": "faaad066-30b4-4997-a438-242b0752d7e1",
    "merchant_account_id": "default",
    "method": "card",
    "payment_service_definition_id": "stripe",
    "status": "pending",
    "type": "payment-service"
  }
}

This endpoint requires the payment-services.write scope.

Authorizations

Authorizationheaderrequired
string

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

Body

application/json
accepted_countriesrequired
string[]

A list of countries that this payment service needs to support in ISO two-letter code format.

accepted_currenciesrequired
string[]

A list of currencies that this payment service needs to support in ISO 4217 three-letter code format.

active
Default: true
boolean

Defines if this service is currently active or not.

display_namerequired
string

A custom name for the payment service. This will be shown in the Admin UI.

fieldsrequired
object[]

A list of fields, each containing a key-value pair for each field defined by the definition for this payment service e.g. for stripe-card secret_key is required and so must be sent within this field.

merchant_profile
object

Configuration for each supported card scheme.

network_tokens_enabled
boolean | null

Defines if network tokens are enabled for the service. This feature can only be enabled if the payment service is set as open_loop and the PSP is set up to accept network tokens.

If this value is not provided or is set to null, it will be set to the value of network_tokens_default in the payment service definition.

If network_tokens_toggle is false in the payment service definition, network_tokens_enabled should either not be provided or set to null, or it will fail with a validation error.

open_loop
boolean | null

Defines if the service works as an open-loop service. This feature can only be enabled if the PSP is set up to accept previous scheme transaction IDs.

If this value is not provided or is set to null, it will be set to the value of open_loop in the payment service definition.

If open_loop_toggle is false in the payment service definition, open_loop should either not be provided or set to null, or it will fail with a validation error.

payment_method_tokenization_enabled
Default: false
boolean

Defines if tokenization is enabled for the service. This feature can only be enabled if the payment service is NOT set as open_loop and the PSP is set up to tokenize.

payment_service_definition_idrequired
string

The ID of the payment service to use.

three_d_secure_enabled
Default: false
boolean

Defines if 3-D Secure is enabled for the service (can only be enabled if the payment service definition supports the three_d_secure_hosted feature). This does not affect pass through 3-D Secure data.

Response

201 - application/json
accepted_countries
string[]

A list of countries for which this service is enabled, in ISO two-letter code format.

accepted_currencies
string[]

A list of currencies for which this service is enabled, in ISO 4217 three-letter code format.

active
Default: true
boolean

Defines if this service is currently active or not.

created_at
string

The date and time when this service was created.

display_name
string

The custom name set for this service.

fields
object[]

A list of fields, each containing a key-value pair for each field configured for this payment service. Fields marked as secret (see Payment Service Definition) are not returned.

id
string

The ID of this payment service.

merchant_account_id
string

The unique ID for a merchant account.

merchant_profile
object

An object containing a key for each supported card scheme (Amex, Discover, Mastercard and Visa), and for each key an object with the merchant profile for this service and the corresponding scheme.

method
enum<string>

The payment method that this service handles.

Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
checkout-session,
click-to-pay,
clearpay,
dana,
dcb,
eps,
fortumo,
gcash,
giropay,
gocardless,
googlepay,
gopay,
grabpay,
ideal,
id,
kakaopay,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
paymaya,
paypal,
paypalpaylater,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
sofort,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
venmo,
waave,
wechat,
zippay
network_tokens_enabled
boolean

Defines if network tokens are enabled for the service. This feature can only be enabled if the payment service is set as open_loop and the PSP is set up to accept network tokens.

open_loop
boolean

Defines if the service works as an open-loop service. This feature can only be enabled if the PSP is set up to accept previous scheme transaction IDs.

payment_method_tokenization_enabled
Default: false
boolean

Defines if tokenization is enabled for the service. This feature can only be enabled if the payment service is NOT set as open_loop and the PSP is set up to tokenize.

payment_service_definition_id
string

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

status
enum<string>

The current status of this service. This will start off as pending, move to created, and might eventually move to an error status if and when the credentials are no longer valid.

Available options:
pending,
created,
failed
three_d_secure_enabled
Default: false
boolean

Defines if 3-D Secure is enabled for the service (can only be enabled if the payment service definition supports the three_d_secure_hosted feature). This does not affect pass through 3-D Secure data.

type
enum<string>

The type of this resource.

Available options:
payment-service
updated_at
string

The date and time when this service was last updated.

webhook_url
string | null

The URL that needs to be configured with this payment service as the receiving endpoint for webhooks from the service to Gr4vy. Currently, Gr4vy does not yet automatically register webhooks on setup, and therefore webhooks need to be registered manually by the merchant.