Skip to main content
POST
/
merchant-accounts
New merchant account
using RestSharp;


var options = new RestClientOptions("https://api.sandbox.{id}.gr4vy.app/merchant-accounts");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n  \"id\": \"plantly-uk\",\n  \"display_name\": \"Plantly UK\",\n  \"outbound_webhook_url\": \"https://www.example.com/webhook\",\n  \"outbound_webhook_username\": \"gr4vy\",\n  \"outbound_webhook_password\": \"super-secret-password\",\n  \"visa_network_tokens_requestor_id\": \"e50fa0da-903d-4d54-aacc-4cac57d48df2\",\n  \"visa_network_tokens_app_id\": \"ca12b3d0-4e23-41a9-906f-e5cbb8e6a731\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);
{
  "type": "merchant-account",
  "id": "plantly-uk",
  "display_name": "Plantly UK",
  "outbound_webhook_url": "https://www.example.com/webhook",
  "outbound_webhook_username": "gr4vy",
  "visa_network_tokens_requestor_id": "e50fa0da-903d-4d54-aacc-4cac57d48df2",
  "visa_network_tokens_app_id": "ca12b3d0-4e23-41a9-906f-e5cbb8e6a731",
  "created_at": "2022-02-01T14:20:00.000+00:00",
  "updated_at": "2022-02-01T14:20:00.000+00:00"
}
This endpoint requires the merchant-accounts.write 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 create a merchant account.

​
id
string

The unique ID for the merchant account.

Required string length: 1 - 22
Example:

"plantly-uk"

​
display_name
string

The human-readable name of the merchant account.

Required string length: 1 - 255
Example:

"Plantly UK"

​
outbound_webhook_url
string | null

The optional URL where webhooks will be received.

Example:

"https://www.example.com/webhook"

​
outbound_webhook_username
string | null

The optional username to use when outbound_webhook_url is configured and requires basic authentication.

Example:

"gr4vy"

​
outbound_webhook_password
string | null

The optional password to use when outbound_webhook_url is configured and requires basic authentication.

Example:

"super-secret-password"

​
visa_network_tokens_requestor_id
string | null

Requestor ID provided for Visa after onboarding to use Network Tokens. The requestor ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
visa_network_tokens_app_id
string | null

Application ID provided for Visa after onboarding to use Network Tokens. The application ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
amex_network_tokens_requestor_id
string | null

Requestor ID provided for Amex after onboarding to use Network Tokens. The requestor ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
amex_network_tokens_app_id
string | null

Application ID provided for Amex after onboarding to use Network Tokens. The application ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
mastercard_network_tokens_requestor_id
string | null

Requestor ID provided for Mastercard after onboarding to use Network Tokens. The requestor ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
mastercard_network_tokens_app_id
string | null

Application ID provided for Mastercard after onboarding to use Network Tokens. The application ID must be unique across all schemes and merchant accounts.

Maximum string length: 300
Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
loon_client_key
string | null

Client key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get configured.
  • If the field is set to null, the other loon_* fields must be set to null as well.
Minimum string length: 1
​
loon_secret_key
string | null

Secret key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get configured.
  • If the field is set to null, the other loon_* fields must be set to null as well.
Minimum string length: 1
​
loon_accepted_schemes
enum<string>[] | null

Card schemes accepted when creating jobs using this set of Loon API keys. Loon is the Account Updater service used by Gr4vy.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get configured.
  • If the field is set to null, the other loon_* fields must be set to null as well.
Available options:
accel,
amex,
bancontact,
carte-bancaire,
cirrus,
culiance,
dankort,
diners-club,
discover,
eftpos-australia,
elo,
hipercard,
jcb,
maestro,
mastercard,
mir,
nyce,
other,
pulse,
rupay,
star,
uatp,
unionpay,
visa,
null
​
over_capture_amount
number | null

The maximum monetary amount allowed for over-capture, in the smallest currency unit, for example 1299 cents to allow for an over-capture of $12.99.

Required range: 1 <= x <= 99999999
Example:

1000

​
over_capture_percentage
number | null

The maximum percentage allowed for over-capture, for example 25 to allow for an over-capture of 25% of the original transaction amount.

Required range: 1 <= x <= 99999999
Example:

20

​
account_updater_enabled
boolean
default:false

Whether the Realtime Account Updater service is enabled for this merchant account. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to false, the Account Updater service doesn't get called if a payment fails with expired or invalid card details.
  • If the field is set to true, the service is called. Please note that for this to work the other account_updater_* fields must be set as well.
Example:

true

​
account_updater_request_encryption_key
string | null

The public key used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-encryption-key"

​
account_updater_request_encryption_key_id
string | null

The public key ID used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-encryption-key-id"

​
account_updater_response_decryption_key
string | null

The private key used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-decryption-key"

​
account_updater_response_decryption_key_id
string | null

The private key ID used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-decryption-key-id"

Response

Returns the created merchant account.

​
type
enum<string>

merchant-account.

Available options:
merchant-account
Example:

"merchant-account"

​
id
string

The ID for this merchant account.

Example:

"plantly-uk"

​
display_name
string

The display name of this merchant account.

Example:

"Plantly UK"

​
outbound_webhook_url
string<uri> | null

The optional URL where webhooks will be received.

Example:

"https://www.example.com/webhook"

​
outbound_webhook_username
string | null

The optional username to use when outbound_webhook_url is configured and requires basic authentication.

Example:

"gr4vy"

​
outbound_webhook_password
string | null

The optional password to use when outbound_webhook_url is configured and requires basic authentication.

If the field is not null, the value is masked to avoid exposing sensitive information.

Example:

"********"

​
visa_network_tokens_requestor_id
string | null

Requestor ID provided for Visa after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
visa_network_tokens_app_id
string | null

Application ID provided for Visa after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
amex_network_tokens_requestor_id
string | null

Requestor ID provided for Amex after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
amex_network_tokens_app_id
string | null

Application ID provided for Amex after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
mastercard_network_tokens_requestor_id
string | null

Requestor ID provided for Mastercard after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
mastercard_network_tokens_app_id
string | null

Application ID provided for Mastercard after onboarding to use Network Tokens.

Example:

"e50fa0da-903d-4d54-aacc-4cac57d48df2"

​
loon_client_key
string | null

Client key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy.

Example:

"7DD771287D0024BA418F8F7ECC7DF1CD"

​
loon_secret_key
string | null

Secret key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy.

If the field is not null, the value is masked to avoid exposing sensitive information.

Example:

"********"

​
loon_accepted_schemes
enum<string>[] | null

Card schemes accepted when creating jobs using this set of Loon API keys. Loon is the Account Updater service used by Gr4vy.

Available options:
accel,
amex,
bancontact,
carte-bancaire,
cirrus,
culiance,
dankort,
diners-club,
discover,
eftpos-australia,
elo,
hipercard,
jcb,
maestro,
mastercard,
mir,
nyce,
other,
pulse,
rupay,
star,
uatp,
unionpay,
visa,
null
Example:
["mastercard", "visa"]
​
account_updater_enabled
boolean
default:false

Whether the Realtime Account Updater service is enabled for this merchant account. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to false, the Account Updater service doesn't get called if a payment fails with expired or invalid card details.
  • If the field is set to true, the service is called. Please note that for this to work the other account_updater_* fields must be set as well.
Example:

true

​
account_updater_request_encryption_key
string | null

The public key used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-encryption-key"

​
account_updater_request_encryption_key_id
string | null

The public key ID used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-encryption-key-id"

​
account_updater_response_decryption_key
string | null

The private key used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-decryption-key"

​
account_updater_response_decryption_key_id
string | null

The private key ID used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired.

  • If the field is not set or if it's set to null, the Account Updater service doesn't get called.
  • If the field is set, the other account_updater_* fields must be set as well.
Example:

"example-decryption-key-id"

​
created_at
string<date-time>

The date and time when this merchant account was created.

Example:

"2022-02-01T14:20:00.000+00:00"

​
updated_at
string<date-time>

The date and time when this merchant account was updated.

Example:

"2022-02-01T14:20:00.000+00:00"

​
over_capture_amount
number | null

The maximum monetary amount allowed for over-capture, in the smallest currency unit, for example 1299 cents to allow for an over-capture of $12.99.

Required range: 1 <= x <= 99999999
Example:

1000

​
over_capture_percentage
number | null

The maximum percentage allowed for over-capture, for example 25 to allow for an over-capture of 25% of the original transaction amount.

Required range: 1 <= x <= 99999999
Example:

20