POST
/
payment-services

This endpoint requires the payment-services.write scope.

Authorizations

​
Authorization
string
headerrequired

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

Body

application/json

Request body for activating a payment service.

​
payment_service_definition_id
string
required

The ID of the payment service to use.

Required string length: 1 - 50
​
display_name
string
required

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

Required string length: 1 - 50
​
fields
object[]
required

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.

​
accepted_countries
string[]
required

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

​
accepted_currencies
string[]
required

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

​
reporting_fields
object[]

The reporting_fields field should contain a list of key-value pairs. Each key-value pair represents a reporting field defined by the payment service. For example, when enabling settlement reporting for nuvei-card, the ssh_username field is required and must be included in reporting_fields.

​
three_d_secure_enabled
boolean
default: false

Defines if 3-D Secure is enabled for the service. This feature 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.

​
merchant_profile
object

Configuration for each supported card scheme.

​
active
boolean
default: true

Defines if this service is currently active or not.

​
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
boolean | null

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.

​
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.

​
settlement_reporting_enabled
boolean
default: false

Defines if settlement reporting is enabled for the service. This feature can only be enabled if the payment service definition supports the settlement_reporting feature.

Response

201 - application/json

An active, configured payment service.

​
type
enum<string>

The type of this resource.

Available options:
payment-service
​
id
string

The ID of this payment service.

Required string length: 1 - 200
​
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
boolean
default: true

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.

Required string length: 1 - 200
​
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.

​
reporting_fields
object[]

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

​
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,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
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
boolean
default: false

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.

Required string length: 1 - 50
​
settlement_reporting_enabled
boolean

Defines if settlement reporting is enabled for the service. This feature can only be enabled if the payment service definition supports the settlement_reporting feature.

​
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
boolean
default: false

Defines if 3-D Secure is enabled for the service. This feature 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.

​
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.

Was this page helpful?

List payment servicesGet payment service