Payments

Payment Initiation

Initiate a single payment and retrieve information on the status of the transaction.

Technical

Payment Initiation API's can be used to send payment orders for a current account and check their processing status. These API's can be part of multiple product offerings. Also, the functionality of the API depends on the product offering.

Updated in v1.01

  • Sandbox now live
  • Updated OAuth2 in YAML file
  • Updated documentation for Sandbox
  • Minor improvements

Open API Specification

Click here to download the Open API Specification of the Payment Initiation API in yaml format.

Environments

Sandbox: https://api-sandbox.abnamro.com

Production: https://api.abnamro.com

Access Token

Payment Initiation API uses client authentication OAuth for registring payments as described here. To use the API, you need to obtain an access token from the Authentication API with the one or more of the following scopes:

SEPA Scopes
Operation Scopes SEPA Description
POST Payments psd2:payment:sepa:write To register a SEPA payment for authorization by the accountholder. You can get this scope through client credentials
PUT Payments psd2:payment:sepa:write To release SEPA payment after authorization by the accountholder. You get this scope through consent from the account holder
GET Payments psd2:payment:sepa:read To request the status of a SEPA payment. You get this scope through consent from the account holder
XBORDER Scopes
Operation Scopes non-SEPA or UK Description
POST Payments psd2:payment:xborder:write To register a xborder payment for authorization by the accountholder. You can get this scope through client credentials
PUT Payments psd2:payment:xborder:write To release xborder payment after authorization by the accountholder. You get this scope through consent from the account holder

POST Payments

POST v1/payments

This operation will register a SEPA payment at the bank for further authorization by the account holder through the consent application. The access token from the consent can be used in PUT payments to execute the registered payment.

Note: UK payments in EUR have to be sent in using payments/xborder.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
initiatingpartyAccountNumber String Body false The account number in IBAN format of the ordering party, initiating the transaction, if omitted the account number will be selected during the authorization of the payment. Also the account number can be changed by the account holder during the authorization of the payment
counterpartyAccountNumber String Body true The account number in IBAN format of the counterparty
counterpartyName String Body true The name of the counterparty. 70 characters are allowed
amount Number Body true The amount of the transaction always positive
currency String Body false The currency of the transaction, only EUR allowed. If omitted EUR is assumed
requestedExecutionDate String Body false The date the payment needs to be executed. If ommitted the payment will be directly processed
remittanceInfo String Body false Information for the beneficiary about the payment. 140 characters are allowed
structuredRemittanceInfo Object Body false A group identifying structured remittance information. Either unstructured remittanceInfo can be used or structuredRemittanceInfo
issuer String structuredRemittanceInfo true 3 types of issuers for structured remittance information are supported. CUR for Dutch payment reference, BBA for Belgium payment reference and ISO for ISO payment reference
reference String structuredRemittanceInfo true The structured remittance information
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
accountNumber String Body false IBAN of the initiating party
transactionId String Body true Unique id generated for the registered payment. Is required input for PUT Payments
status String Body false The current status of the payment which is STORED after successful registration

PUT Payments

PUT /v1/payments/{transactionId}

This operation will execute an authorized and registered SEPA payment at the bank. Authorization by the account holder is needed through the consent application to obtain a access token. The TransactionId is received as response of the POST Payments.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
transactionId String Path true Unique id generated for the registered payment
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
accountNumber String Body false IBAN of the initiating party
transactionId String Body true Unique id generated for the registered payment
status String Body false The current status of the payment which is IN PROGRESS, SCHEDULED, EXECUTED or REJECTED after successful execution (PUT)

GET Payments

GET /v1/payments/{transactionId}

This operation will retrieve the current status of a payment.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
transactionId String Path true Unique id generated for the payment
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
accountNumber String Body false IBAN of the initiating party
transactionId String Body true Unique id generated for the registered payment
status String Body false The current status of the payment. See Status Values table below for details

Status Values

Value Description
STORED Payment has been sent in using POST, but no consent has been received yet
AUTHORIZED Payment has been authorized through consent by account holder. Payment can be executed using PUT Payments
INPROGRESS Registered payment has been released and is being processed
SCHEDULED Future dated payment is scheduled for processing
EXECUTED Payment is booked
REJECTED Payment is rejected. This can be for example because of invalid beneficiary IBAN, insufficient funds or account restrictions
UNKNOWN Status cannot be retrieved. Try later again

POST payments/xborder

POST /v1/payments/xborder

This operation will register a non-SEPA payment at the bank for further authorization by the account holder through the consent application. The access token from the consent can be used in PUT payments to execute the registered payment. Due to the nature of international interbank communication formats, these type of payments are subject to SWIFT characterset limitations and possible truncation of fields.

Note: Non-SEPA payments are payments made outside the European Economic Area and/or non-EURO currency. Also payments in the UK need to be sent in as crossborder.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
initiatingParty Object Body false A group identifying the account to be used to initiate the payment from, if omitted the accountnumber will be selected during the authorization of the payment
accountNumber String initiatingParty true The account number in IBAN format of the ordering party, initiating the transaction, the account number can be changed by the account holder during the authorization of the payment
accountCurrency String initiatingParty false Currency of the account number, 3 characters ISO 4217 currency code (e.g. EUR or USD). If not provided, the currency of the amount is assumed as the currency of the initiating account
counterParty Object Body true A group identyifing the account of the counter party
name String counterParty true The name of the counterparty
accountNumberType String counterParty true Indicator of the type of accountNumber being used, either IBAN or BBAN (latter for domestic/basic formatting)
accountNumber String counterParty true The IBAN or BBAN formatted account number of the counterparty as indicated by accountNumberType
bankIdentifierType String counterParty true Indicator signifying the type of bankIdentifier used; SWIFTBIC (for a BIC); UKSORTCODE (for a UK sortcode); FEDWIRE (for a US bankcode)
bankIdentifier String counterParty true Specify the BankIdentifier here for the selected bankIdentifierType
amount Number Body true The amount of the transaction, always positive
currency String Body true Currency of the transaction, 3 characters alphabetic ISO-4217 currency (e.g. EUR, USD)
requestedExecutionDate String Body false The date the payment needs to be executed. If ommitted the payment will be directly processed (or when clearing is closed at first possible time)
chargesBearer String Body false Indicator who pays the charges related to the payment BEN = beneficiary, OUR = initiating party, SHA both parties share the charges. If not specified, SHA is assumed. Note in EEA always use SHA
remittanceInfo String Body false Descriptive text that is part of the transaction. 140 characters are allowed
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
accountNumber String Body false IBAN of the initiating party
transactionId String Body true Unique id generated for the registered payment
status String Body false The current status of the payment which is STORED after successful registration

PUT payments/xborder

PUT /v1/payments/xborder/{transactionId}

This operation will execute an authorized and registered non-SEPA payment at the bank. Authorization by the account holder is needed through the consent application to obtain a access token. The transactionId is received as response of the POST Payments.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
transactionId String Path true Unique id generated for the registered payment
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
accountNumber String Body false IBAN of the initiating party
transactionId String Body true Unique id generated for the registered payment
status String Body false The current status of the payment which is IN PROGRESS, SCHEDULED, EXECUTED or REJECTED after successful execution (PUT)

Error Response & Codes

This section describes the error response & the codes being sent by the API.

Error Response Attributes
Name Type In Required Description
code String Body true The code of the error
message String Body true The human readible error message
reference String Body true Reference where to find more information on error
Trace-Id String Body true Unique id generated for every request
status String Body true https error code, 4xx or 5xx
category String Body true Category of error. Values: BAD_REQUEST, FORBIDDEN, INTERNAL_SERVER_ERROR, BACKEND_ERROR, more generic categories can be found on the Get Started page under the section Error Codes.
Error Codes

This section lists the errors that are specific for this API. If your error is not listed here, or you want to know which general errors can occur, you can check on the Get Started page under the section Error Codes.

HTTP status code Error Code Error Description
400 MESSAGE_BAI561_0017 Invalid initiating party account number
400 MESSAGE_BAI561_0018 Invalid counter party account number
400 MESSAGE_BAI561_0019 Initiating Party and counterparty account numbers are same
400 MESSAGE_BAI561_0022 Remittance information has invalid character(s)
400 MESSAGE_BAI561_0023 Counter party name has invalid character(s)
400 MESSAGE_BAI561_0024 Amount is negative or zero
400 MESSAGE_BAI561_0043 Currency is not "EUR"
400 MESSAGE_BAI561_0060 Counterparty account number is blank
400 MESSAGE_BAI561_0061 Counterparty account number length is greater than 34
400 MESSAGE_BAI561_0062 Counterparty account number is not alphanumeric
400 MESSAGE_BAI561_0063 Amount is mandatory
400 MESSAGE_BAI561_0064 Amount is invalid
400 MESSAGE_BAI561_0065 Invalid reference id
400 MESSAGE_BAI561_0066 Invalid request body
400 MESSAGE_BAI561_0067 Mismatch TransactionID call and token
400 MESSAGE_BAI561_0068 Error occurred when status for the payment is other than STORED
400 MESSAGE_BAI561_0070 Counter party account number has length more than 70
400 MESSAGE_BAI561_0071 Counter party account number is BLANK
400 MESSAGE_BAI561_0072 REMITTANCE info field length is more than 140 characters
400 MESSAGE_BAI561_0073 Account number type is invalid
400 MESSAGE_BAI561_0075 Acccount number type not present
400 MESSAGE_BAI561_0076 Currency is mandatory
400 MESSAGE_BAI561_0077 Type is invalid
400 MESSAGE_BAI561_0078 Bank indentifier type is mandatory
400 MESSAGE_BAI561_0079 Counterparty missing in body
400 MESSAGE_BAI561_0080 Invalid chargesbearer
400 MESSAGE_BAI561_0081 Counter party BBAN is invalid
400 MESSAGE_BAI561_0084 Bank identifier type not provided
400 MESSAGE_JA001_0001 Client Id is blank
403 MESSAGE_BAI561_0044 Token does not contain account number
403 MESSAGE_BAI561_0045 Mismatch account number in call and token
403 MESSAGE_BAI561_0046 Wrong scope
403 MESSAGE_BAI561_0047 Scope unknown or missing
403 MESSAGE_BAI561_0048 Wrong granttype for token
403 MESSAGE_DAO375_0004 Date is out of range
403 MESSAGE_DAO375_0005 Insufficient grant level
403 MESSAGE_DAO375_0006 No access to account
403 MESSAGE_DAO375_0007 Client not found
403 MESSAGE_DAO375_0008 No access to account
403 MESSAGE_DAO375_0011 Grant type missing or unknown
404 MESSAGE_BAI561_0028 Wrong input
404 MESSAGE_BAI561_0030 No payment details found
5xx MESSAGE_xxxxxxxxxxx For any 500 error please contact the bank

Characterset

For SEPA payments and crossborder payments the characterset in the table below can be used.

Character set
space
! & ' ( ) + - . / 0 1 2 3 4 5 6 7 8 9 : ? _ ` ,
aAbBcCdDeEfFgGhHiljJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
àÀáÁâÂãÃäÄåÅæÆçÇèÈéÉêÊëËìÌíÍîÎïÏðÐñÑòÒóÓôÔõÕöÖ×øØùÙúÚûÛüÜýÝþÞßÞÿ

Note: For cross border, characters may be converted (e.g. the ":" and "‘") and lines can be truncated because of differences in standards between local payment and clearing system.