Third-party payouts API

To communicate with the Adyen API you should submit HTTP POST requests to corresponding endpoints. These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the Adyen payments platform.

This document lists all endpoints available for you to integrate with the test platform and run QA checks.

Endpoints

SOAP

For the SOAP messaging protocol, all test payment requests must be posted to the following endpoint:

The data schema for corresponding SOAP objects is available at:

JSON and FORM

This is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an Http POST URL).

If your integration uses the /storeDetailAndSubmit or /submit endpoints, you need to migrate to the new endpoints. For more information, refer to Migrate to third-party payouts.

After you are ready to go live, you should switch to either generic or custom live endpoints. For more information, refer to Live endpoints.

ModifyRequest

This class contains data that should be passed in one of the following requests to either confirm or decline a submitted payout:

  • /confirmThirdParty - to confirm the submitted payout.
  • /declineThirdParty - to decline the submitted payout.
Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be required for a particular payment request.

merchantAccount String (tick)

The merchant account identifier you want to process the (transaction) request with.

originalReference String (tick)

The PSP reference received in the submit payout response.

ModifyResponse

If the message is syntactically valid and merchantAccount is correct, you receive a response with the following.

Field Type Required Description
pspReference String (tick)

A new reference to uniquely identify this request. This reference is the pspReference of the payout.

response String (tick)

The response:

  • In case of success, it is either payout-confirm-received or payout-decline-received.
  • In case of an error, an informational message is returned.

You do not receive notifications if the payout is declined.

StoreDetailAndSubmitRequest

This class contains data that should be passed in the /storeDetailAndSubmitThirdParty request to initiate a payout.

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be required for a particular request.

amount Amount (tick)

A container object for the payable amount information of the transaction.

bank
BankAccount (error)

A container for bank account data.

This field is mandatory if the card details are not provided.

billingAddress Address (error) The billing address.
card Card (error)

A container for card data.

This field is mandatory if bank details are not provided.

dateOfBirth Date (error)

The date of birth.

Format: ISO-8601; example: YYYY-MM-DD

For Paysafecard it must be the same as used when registering the Paysafecard account.

This field is mandatory for natural persons. 

entityType String (tick)

The type of the entity the payout is processed for.

Allowed values:

  • NaturalPerson
  • Company
fraudOffset Int (error)

An integer value that is added to the normal fraud score. The value can be either positive or negative.

merchantAccount String (tick)

The merchant account identifier you want to process the (transaction) request with.

nationality String (tick)

The shopper's nationality.

A valid value is an ISO 2-character country code (e.g. 'NL').

recurring Object (tick)

A container for the type of recurring contract to be retrieved.

The recurring.contract must be set to PAYOUT.

reference String (tick) The (merchant) reference for this payment. This reference will be used in all communication to the merchant about the status of the Payout payment. Although it is a good idea to make sure it is unique, this is not a requirement.
selectedBrand
String (error)

The name of the brand to make a payout to.

For Paysafecard it must be set to paysafecard.

shopperEmail String (tick)

The shopper's email address.

shopperName Name (tick)

The shopper's name.

If the entityType is Company, submit the company name in the shopperName.lastName field.

shopperReference String (tick)

The shopper's reference for the payment transaction.

shopperStatement String (error)

The description of this payout. This description is shown on the bank statement of the shopper (if this is supported by the chosen payment method).

socialSecurityNumber String (error) The shopper's social security number.

StoreDetailAndSubmitResponse

If the message is syntactically valid and merchantAccount is correct, you receive a payout-submit-received response with the following fields:

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be returned in a particular response.

pspReference String (tick)

A new reference to uniquely identify this request.

resultCode String (tick)

The response:

In case of success is payout-submit-received.

In case of an error, an informational message is returned.

refusalReason String (error)

In case of refusal, an informational message for the reason.

StoreDetailRequest

This class contains data that should be passed in the /storeDetail request to store payout details.

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be required for a particular request.

bank BankAccount (error)

A container for bank account data.

This field is mandatory if the card details are not provided.


billingAddress Address (error) The billing address.
card Card (tick)

A container for card data.

This field is mandatory if bank details are not provided.


dateOfBirth Date (tick)

The date of birth.

Format: ISO-8601; example: YYYY-MM-DD

For Paysafecard it must be the same as used when registering the Paysafecard account.

This field is mandatory for natural persons. 

entityType String (tick)

The type of the entity the payout is processed for.

Allowed values:

  • NaturalPerson
  • Company
fraudOffset Int (error)

An integer value that is added to the normal fraud score. The value can be either positive or negative.

merchantAccount String (tick)

The merchant account identifier you want to process the (transaction) request with.

nationality String (tick)

The shopper's nationality.

A valid value is an ISO 2-character country code (e.g. 'NL').

recurring Object (tick)

A container for the type of recurring contract to be retrieved.

The recurring.contract must be set to "PAYOUT".

selectedBrand String (error)

The name of the brand to make a payout to.

For Paysafecard it must be set to paysafecard.

shopperEmail String (tick) The shopper's email address.
shopperName Name (tick)

The shopper's name.

In case the entityType is Company, the shopperName.lastName must contain the company name.

shopperReference String (tick) The shopper's reference for the payment transaction.
socialSecurityNumber String (error) The shopper's social security number.

StoreDetailResponse

If the StoreDetailRequest message is syntactically valid and merchantAccount is correct, you receive a response with the following fields:

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be returned in a particular response.

pspReference String (tick)

A new reference to uniquely identify this request.

recurringDetailReference String (tick)

The token which you can use later on for submitting the payout.

resultCode String (tick)

The result code of the transaction. Success indicates that the details were stored successfully.

SubmitRequest

This class contains data that should be passed in the /submitThirdParty  request to initiate a payout.

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be required for a particular request.

amount Amount (tick)

A container object for the payable amount information of the transaction.

dateOfBirth Date (error)

The date of birth.

Format: ISO-8601; example: YYYY-MM-DD

For Paysafecard it must be the same as used when registering the Paysafecard account.

This field is mandatory for natural persons. 

This field is required to update the existing dateOfBirth that is associated with this recurring contract.

entityType String (error)

The type of the entity the payout is processed for.

Allowed values:

  • NaturalPerson
  • Company

This field is required to update the existing entityType that is associated with this recurring contract.

fraudOffset Int (error)

An integer value that is added to the normal fraud score. The value can be either positive or negative.

merchantAccount String (tick)

The merchant account identifier you want to process the (transaction) request with.

nationality String (error)

The shopper's nationality.

A valid value is an ISO 2-character country code (e.g. 'NL').

This field is required to update the existing nationality that is associated with this recurring contract.

recurring Object (tick)

A container for the type of recurring contract to be retrieved.

The recurring.contract must be set to "PAYOUT".

reference String (tick)

The merchant reference for this payment. This reference will be used in all communication to the merchant about the status of the Payout payment. Although it is a good idea to make sure it is unique, this is not a requirement.

selectedRecurringDetailReference String (tick)

This is the recurringDetailReference you want to use for this payout.

You can use the value LATEST to select the most recently used recurring detail.

shopperEmail String (tick)

The shopper's email address.

shopperName Name (error)

The shopper's name.

In case the entityType is Company, the shopperName.lastName must contain the company name.

This field is required to update the existing shopperName associated with a recurring contract.

shopperReference String (tick) The shopper's reference for the payout transaction.
shopperStatement String (error)

The description of this payout. This description is shown on the bank statement of the shopper (if this is supported by the chosen payment method).

socialSecurityNumber String (error) The shopper's social security number.

SubmitResponse

If the message is syntactically valid and merchantAccount is correct, you receive a payout-submit-received response with the following fields:

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be returned in a particular response.

pspReference String (tick)

A new reference to uniquely identify this request.

resultCode String (tick)

The response:

In case of success is payout-submit-received.

In case of an error, an informational message is returned.

refusalReason String (error)

In case of refusal, an informational message for the reason.