@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Adyen Payout API
@base https://pal-test.adyen.com/pal/servlet/Payout/v68
@version 68
@auth ApiKey X-API-Key in header | Bearer basic
@common_fields {merchantAccount: str # The merchant account identifier, with which you want to process the transaction.}
@endpoints 6
@toc confirmThirdParty(1), declineThirdParty(1), payout(1), storeDetail(1), storeDetailAndSubmitThirdParty(1), submitThirdParty(1)

@group confirmThirdParty
@endpoint POST /confirmThirdParty
@desc Confirm a payout
@required {originalReference: str # The PSP reference received in the `/submitThirdParty` response.}
@optional {additionalData: map # This field contains additional data, which may be required for a particular payout request.}
@returns(200) {additionalData: map, pspReference: str, response: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"merchantAccount":"YOUR_MERCHANT_ACCOUNT","originalReference":"9913140798220028"}

@endgroup

@group declineThirdParty
@endpoint POST /declineThirdParty
@desc Cancel a payout
@required {originalReference: str # The PSP reference received in the `/submitThirdParty` response.}
@optional {additionalData: map # This field contains additional data, which may be required for a particular payout request.}
@returns(200) {additionalData: map, pspReference: str, response: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"merchantAccount":"YOUR_MERCHANT_ACCOUNT","originalReference":"9913140798220028"}

@endgroup

@group payout
@endpoint POST /payout
@desc Make an instant card payout
@required {amount: map{currency!: str, value!: int(int64)}, reference: str # The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement. If you need to provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters.}
@optional {billingAddress: map{city!: str, country!: str, houseNumberOrName!: str, postalCode!: str, stateOrProvince: str, street!: str}, card: map{cvc: str, expiryMonth: str, expiryYear: str, holderName: str, issueNumber: str, number: str, startMonth: str, startYear: str}, fraudOffset: int(int32) # An integer value that is added to the normal fraud score. The value can be either positive or negative., fundSource: map{additionalData: map, billingAddress: map, card: map, shopperEmail: str, shopperName: map, telephoneNumber: str}, recurring: map{contract: str, recurringDetailName: str, recurringExpiry: str(date-time), recurringFrequency: str, tokenService: str}, selectedRecurringDetailReference: str # The `recurringDetailReference` you want to use for this payment. The value `LATEST` can be used to select the most recently stored recurring detail., shopperEmail: str # The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks. > Required for Visa and JCB transactions that require 3D Secure 2 authentication if you did not include the `telephoneNumber`., shopperInteraction: str(Ecommerce/ContAuth/Moto/POS) # Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer. For the web service API, Adyen assumes Ecommerce shopper interaction by default.  This field has the following possible values: * `Ecommerce` - Online transactions where the cardholder is present (online). For better authorisation rates, we recommend sending the card security code (CSC) along with the request. * `ContAuth` - Card on file and/or subscription transactions, where the cardholder is known to the merchant (returning customer). If the shopper is present (online), you can supply also the CSC to improve authorisation (one-click payment). * `Moto` - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone. * `POS` - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal., shopperName: map{firstName!: str, lastName!: str}, shopperReference: str # Required for recurring payments.  Your reference to uniquely identify this shopper, for example user ID or account ID. The value is case-sensitive and must be at least three characters. > Your reference must not include personally identifiable information (PII) such as name or email address., telephoneNumber: str # The shopper's telephone number.  The phone number must include a plus sign (+) and a country code (1-3 digits), followed by the number (4-15 digits). If the value you provide does not follow the guidelines, we do not submit it for authentication. > Required for Visa and JCB transactions that require 3D Secure 2 authentication, if you did not include the `shopperEmail`.}
@returns(200) {additionalData: map, authCode: str, dccAmount: map{currency: str, value: int(int64)}, dccSignature: str, fraudResult: map{accountScore: int(int32), results: [any]}, issuerUrl: str, md: str, paRequest: str, pspReference: str, refusalReason: str, resultCode: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"amount":{"value":2500,"currency":"USD"},"card":{"number":"4111111111111111","expiryMonth":"03","expiryYear":"2030","holderName":"John Smith"},"billingAddress":{"houseNumberOrName":"121","street":"Brannan Street","city":"Beverly Hills","postalCode":"90210","stateOrProvince":"CA","country":"US"},"merchantAccount":"YOUR_MERCHANT_ACCOUNT","reference":"P9999999999999999","shopperName":{"firstName":"John","lastName":"Smith"}}

@endgroup

@group storeDetail
@endpoint POST /storeDetail
@desc Store payout details
@required {dateOfBirth: str(date) # The date of birth. Format: [ISO-8601](https://www.w3.org/TR/NOTE-datetime); 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: str(NaturalPerson/Company) # The type of the entity the payout is processed for., nationality: str # The shopper's nationality.  A valid value is an ISO 2-character country code (e.g. 'NL')., recurring: map{contract: str, recurringDetailName: str, recurringExpiry: str(date-time), recurringFrequency: str, tokenService: str}, shopperEmail: str # The shopper's email address., shopperReference: str # The shopper's reference for the payment transaction.}
@optional {additionalData: map # This field contains additional data, which may be required for a particular request., bank: map{bankAccountNumber: str, bankCity: str, bankLocationId: str, bankName: str, bic: str, countryCode: str, iban: str, ownerName: str, taxId: str}, billingAddress: map{city!: str, country!: str, houseNumberOrName!: str, postalCode!: str, stateOrProvince: str, street!: str}, card: map{cvc: str, expiryMonth: str, expiryYear: str, holderName: str, issueNumber: str, number: str, startMonth: str, startYear: str}, fraudOffset: int(int32) # An integer value that is added to the normal fraud score. The value can be either positive or negative., selectedBrand: str # The name of the brand to make a payout to.  For Paysafecard it must be set to `paysafecard`., shopperName: map{firstName!: str, lastName!: str}, socialSecurityNumber: str # The shopper's social security number., telephoneNumber: str # The shopper's phone number.}
@returns(200) {additionalData: map, pspReference: str, recurringDetailReference: str, resultCode: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"merchantAccount":"YOUR_MERCHANT_ACCOUNT","recurring":{"contract":"PAYOUT"},"bank":{"bankName":"AbnAmro","bic":"ABNANL2A","countryCode":"NL","iban":"NL32ABNA0515071439","ownerName":"Adyen","bankCity":"Amsterdam","taxId":"bankTaxId"},"shopperEmail":"shopper@email.com","shopperReference":"YOUR_UNIQUE_SHOPPER_ID","shopperName":{"firstName":"Adyen","lastName":"Test"},"dateOfBirth":"1990-01-01","entityType":"Company","nationality":"NL","billingAddress":{"houseNumberOrName":"17","street":"Teststreet 1","city":"Amsterdam","stateOrProvince":"NY","country":"US","postalCode":"12345"}}

@endgroup

@group storeDetailAndSubmitThirdParty
@endpoint POST /storeDetailAndSubmitThirdParty
@desc Store details and submit a payout
@required {amount: map{currency!: str, value!: int(int64)}, dateOfBirth: str(date) # The date of birth. Format: [ISO-8601](https://www.w3.org/TR/NOTE-datetime); 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: str(NaturalPerson/Company) # The type of the entity the payout is processed for., nationality: str # The shopper's nationality.  A valid value is an ISO 2-character country code (e.g. 'NL')., recurring: map{contract: str, recurringDetailName: str, recurringExpiry: str(date-time), recurringFrequency: str, tokenService: str}, reference: str # The merchant reference for this payment. This reference will be used in all communication to the merchant about the status of the payout. Although it is a good idea to make sure it is unique, this is not a requirement., shopperEmail: str # The shopper's email address., shopperReference: str # The shopper's reference for the payment transaction.}
@optional {additionalData: map # This field contains additional data, which may be required for a particular request., bank: map{bankAccountNumber: str, bankCity: str, bankLocationId: str, bankName: str, bic: str, countryCode: str, iban: str, ownerName: str, taxId: str}, billingAddress: map{city!: str, country!: str, houseNumberOrName!: str, postalCode!: str, stateOrProvince: str, street!: str}, card: map{cvc: str, expiryMonth: str, expiryYear: str, holderName: str, issueNumber: str, number: str, startMonth: str, startYear: str}, fraudOffset: int(int32) # An integer value that is added to the normal fraud score. The value can be either positive or negative., selectedBrand: str # The name of the brand to make a payout to.  For Paysafecard it must be set to `paysafecard`., shopperName: map{firstName!: str, lastName!: str}, shopperStatement: str # 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: str # The shopper's social security number., telephoneNumber: str # The shopper's phone number.}
@returns(200) {additionalData: map, pspReference: str, refusalReason: str, resultCode: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"merchantAccount":"YOUR_MERCHANT_ACCOUNT","recurring":{"contract":"PAYOUT"},"amount":{"value":2000,"currency":"EUR"},"bank":{"bankName":"Commerzbank","iban":"DE87123456781234567890","countryCode":"DE","ownerName":"Simon Hopper"},"reference":"Your Reference","shopperEmail":"s.hopper@test.com","shopperReference":"YOUR_SHOPPER_REFERENCE","shopperName":{"firstName":"Adyen","lastName":"Test"},"dateOfBirth":"1990-01-01","entityType":"Company","nationality":"NL"}

@endgroup

@group submitThirdParty
@endpoint POST /submitThirdParty
@desc Submit a payout
@required {amount: map{currency!: str, value!: int(int64)}, recurring: map{contract: str, recurringDetailName: str, recurringExpiry: str(date-time), recurringFrequency: str, tokenService: str}, reference: str # The merchant reference for this payout. This reference will be used in all communication to the merchant about the status of the payout. Although it is a good idea to make sure it is unique, this is not a requirement., selectedRecurringDetailReference: str # 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: str # The shopper's email address., shopperReference: str # The shopper's reference for the payout transaction.}
@optional {additionalData: map # This field contains additional data, which may be required for a particular request., dateOfBirth: str(date) # 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: str(NaturalPerson/Company) # 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(int32) # An integer value that is added to the normal fraud score. The value can be either positive or negative., nationality: str # 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., shopperName: map{firstName!: str, lastName!: str}, shopperStatement: str # 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: str # The shopper's social security number.}
@returns(200) {additionalData: map, pspReference: str, refusalReason: str, resultCode: str} # OK - the request has succeeded.
@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}
@example_request {"amount":{"currency":"EUR","value":1000},"merchantAccount":"YOUR_MERCHANT_ACCOUNT","recurring":{"contract":"PAYOUT"},"reference":"PayoutPayment-0001","shopperEmail":"shopper@email.com","shopperReference":"YOUR_UNIQUE_SHOPPER_ID","shopperName":{"firstName":"Adyen","lastName":"Test"},"dateOfBirth":"1990-01-01","entityType":"Company","nationality":"NL","selectedRecurringDetailReference":"LATEST"}

@endgroup

@end