Payments
Initiate payments and retrieve information.
Technical
Payment Initiation APIs can be used to send payment orders for a current account and check their processing status. These APIs can be part of multiple product offerings. Also, the functionality of the API depends on the product offering.
Payment Initiation version 1.1.0
New in this version:
- Standing payment orders
- Batch payments
- Delete payment method
- Updated YAML file to OpenAPI 3 specifications
- Textual improvements based on feedback
Open API Specification
To download the Open API Specification of the Payment Initiation API in YAML format, click here.
Environments
Sandbox: https://api-sandbox.abnamro.com
Production: https://api.abnamro.com
Access Token
Payment Initiation API uses client authentication OAuth for registering payments as described here. To use this API, you must 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 account holder. Get this scope through client credentials |
| PUT Payments | psd2:payment:sepa:write | To release SEPA payment after authorization by the account holder. Get this scope by consent from the account holder |
| DELETE Payments | psd2:payment:sepa:write | To cancel a future dated payment that has been released. Get this scope by consent from the account holder |
| GET Payments | psd2:payment:sepa:read | To request the status of a SEPA payment. Get this scope by consent from the account holder |
XBORDER Scopes
| Operation | Scopes non-SEPA | Description |
|---|---|---|
| POST Xborder | psd2:payment:xborder:write | To register a xborder payment for authorization by the account holder. Get this scope through client credentials |
| PUT Xborder | psd2:payment:xborder:write | To release xborder payment after authorization by the account holder. Get this scope by consent from the account holder |
Standing Orders Scopes
| Operation | Scopes SEPA NL | Description |
|---|---|---|
| POST Standingorder | psd2:payment:recurrent:sepa:write | To register a standing order for authorization by the account holder. Get this scope through client credentials |
| PUT Standingorder | psd2:payment:recurrent:sepa:write | To activate a standing order after authorization by the account holder. Get this scope by consent from the account holder |
Batch Scopes
| Operation | Scopes SEPA NL | Description |
|---|---|---|
| POST Batch | psd2:payment:batchsct:write | To register a SEPA SCT Batch payment file for authorization by the accountholder in Internet Banking or Access Online. You can get this scope through client credentials |
| POST Batch | psd2:payment:batchsdd:write | To register a SEPA SDD Batch payment file for authorization by the accountholder in Internet Banking or Access Online. You can get this scope through client credentials. The account holder must have a direct debit contract with ABN AMRO |
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, see Authorization and Tutorials for details. The access token from the consent can be used in PUT payments to execute the registered 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 | The API Key for your app from the 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. When the account cannot be authorized, the account holder can select a different account |
| counterpartyAccountNumber | String | Body | true | The account number in IBAN format of the counterparty |
| counterpartyName | String | Body | true | The name of the counterparty. A maximum of 70 characters is allowed |
| amount | Number | Body | true | The amount of the transaction, which is always positive. The maximum amount is equal to that set for the online banking channel (AOL/IB) |
| currency | String | Body | false | Currency of the transaction, 3 characters alphabetic ISO-4217 currency such as EUR or USD. If omitted EUR is assumed |
| requestedExecutionDate | String | Body | false | An optional date on which the payment is to be executed. This date should be no more than 364 days after the current date. If the executiondate is in the past, or if the requested execution date is empty, the payment will be executed immediately, or as soon as possible when clearing is closed. The format of the date must be ISO8601, YYYY-MM-DD. |
| remittanceInfo | String | Body | false | Information for the beneficiary about the payment. This type of information is 'unstructured'. A maximum of 140 characters is 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 |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique Transaction ID of the payment to be used for authorization by the account holder |
| 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 release a registered SEPA payment at the bank for further processing. Authorization by the account holder is needed through the consent application to obtain an access token. The TransactionId is received as response of the POST Payments.
Request Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| transactionId | String | Path | true | Unique ID of the payment that must be released |
| Authorization | String | Header | true | Access token to be passed as a Bearer token |
| API-Key | String | Header | true | The API Key for your app from the Developer Portal |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique ID of the (released) payment |
| status | String | Body | false | The current status of the payment which is IN PROGRESS, SCHEDULED, EXECUTED or REJECTED after successful execution (PUT) |
DELETE Payments
DELETE v1/payments/{transactionId}
This operation will cancel a future dated payment that has been executed using a PUT, which provides a 'SCHEDULED' status. If the future date has passed, the payment can no longer be cancelled. The access token from the consent can be used to delete the future dated payment.
Request Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| transactionId | String | Path | true | Unique ID of the payment that must be cancelled |
| Authorization | String | Header | true | Access token to be passed as a Bearer token |
| API-Key | String | Header | true | The API Key for your app from the Developer Portal |
Response Attributes
A successful cancellation returns a http 204 code without response attributes.
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 | The API Key for your app from the Developer Portal |
| transactionId | String | Path | true | Unique ID generated for the payment |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| transactionId | String | Path | true | Unique ID generated for the registered payment |
| accountNumber | String | Body | false | IBAN of the initiating party |
| status | String | Body | false | The current status of the payment. For details, see Status Values |
Status Values
| Value | Description |
|---|---|
| STORED | Payment has been sent using POST, but consent has not been received |
| AUTHORIZED | Payment has been authorized by consent from the 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 may occur because of: invalid beneficiary IBAN, insufficient funds, or account restrictions |
| UNKNOWN | Status cannot be retrieved. Try again later |
POST Standing Order
POST /v1/payments/standingorder
This operation will register a periodic SEPA payment at the bank for further authorization by the account holder through the consent application, see Authorization and Tutorials for details. The access token from the consent can be used in PUT to execute the registered standing order.
Note: Standing Orders are for NL only, since standing payment order product is not supported in ABN AMRO branches.
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 | The API Key for your app from the Developer Portal |
| startDate | Date | Body | true | Start date of the standing order in the format yyyy-mm-dd. Must be today or maximum of 30 days in future |
| endDate | Date | Body | true | Optional end date of the standing order, in the format: yyyy-mm-dd. If left blank, the end date is indefinite. When filled it must be >= startDate |
| executionRule | String | Body | false | The field is accepted for input, but not used. "following" or "preceeding" are accepted as values (not case sensitive) |
| frequency | String | Body | true | frequency with which the standing order is executed. The 'EventFrequencyCode' of ISO 20022 is supported. The following values are accepted: 'Daily', 'Weekly', 'EveryTwoWeeks', 'Monthly', 'EveryTwoMonths', 'Quarterly', 'SemiAnnual', 'Annual' |
| dayOfExecution | String | Body | false | The field is accepted for input, but not used |
| payment | String | Object | true | The field is accepted for input, but not used |
| initiatingpartyAccountNumber | String | payment | true | The account number in IBAN format of the ordering party, initiating the transaction. When the account cannot be authorized, the account holder can select a different account |
| counterpartyAccountNumber | String | payment | true | The account number in IBAN format of the counterparty |
| counterpartyName | String | payment | true | The name of the counterparty. A maximum of 70 characters is allowed |
| amount | Number | payment | true | The amount of the transaction always positive. The maximum amount is equal to what is set for the online banking channel (AOL/IB) |
| currency | String | payment | false | The currency of the transaction, only EUR is allowed. If omitted EUR is assumed |
| requestedExecutionDate | String | payment | false | The date the payment must be executed. If omitted the payment will be directly processed, or when clearing is closed as soon as possible |
| remittanceInfo | String | payment | false | Information for the beneficiary about the payment. A maximum of 140 characters is allowed |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique Transaction ID of the standing order to be used for authorization by the account holder |
| status | String | Body | false | The current status of the payment which is 'STORED' after successful registration and 'REJECTED' when unsuccessful |
PUT Standing Order
PUT /v1/payments/standingorder/{transactionId}
This operation will activate an authorized and registered standing order at the bank. Authorization by the account holder is needed through the consent application to obtain a access token. For details see Authorization. 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 | The API Key for your app from the Developer Portal |
| transactionId | String | Path | true | Unique ID of the payment that must be released |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique ID of the payment that must be released |
| status | String | Body | false | The current status of the payment which is 'STORED' after successful registration and 'REJECTED' when unsuccessful |
The account holder can cancel the standing order using Internet Banking or Access Online.
POST 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, see Authorization and Tutorials for details. Due to the nature of international interbank communication formats, these type of payments are subject to SWIFT character set limitations and possible truncation of fields.
Note: Non-SEPA payments are payments made outside the European Economic Area or non-EURO currency. Also GBP payments in the UK need to be sent as cross-border.
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 | The API Key for your app from the Developer Portal |
| initiatingParty | Object | Body | false | A group identifying the account that will be used to initiate the payment, if omitted the account number 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, if omitted the account number will be selected during the authorization of the payment. If the account cannot be authorized, the account holder can select a different account |
| accountCurrency | String | initiatingParty | false | Currency of the account number, 3 characters ISO 4217 currency code, such as EUR or USD. If not provided, the currency of the of the initiating account is used |
| counterParty | Object | Body | true | A group identifying the account of the counter party |
| name | String | counterParty | true | The name of the counterparty |
| accountNumberType | String | counterParty | true | Indicates which type of accountNumber is being used, either IBAN or BBAN, BBAN is used 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 | Indicates the type of bankIdentifier used; SWIFTBIC, for a BIC; UKSORTCODE, for a UK sortcode; or 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 which is always positive. The maximum amount is equal to what is set for the online banking channel (AOL/IB) |
| currency | String | Body | true | Currency of the transaction, 3 characters alphabetic ISO-4217 currency such as EUR or USD |
| requestedExecutionDate | String | Body | false | The date the payment must be executed. If omitted the payment will be directly processed, or when clearing is closed as soon as possible |
| chargesBearer | String | Body | false | Indicates 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. Always use SHA in EEA |
| remittanceInfo | String | Body | false | Descriptive text that is part of the transaction. A maximum of 140 characters is allowed |
Future dated payments can be cancelled by the account holder using Internet Banking or Access Online.
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique Transaction ID of the payment to be used for authorization by the account holder |
| status | String | Body | false | The current status of the payment which is STORED after successful registration |
PUT 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 a response to the POST Payments.
Request Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| transactionId | String | Path | true | Unique ID of the payment that must be released |
| Authorization | String | Header | true | Access token to be passed as a Bearer token |
| API-Key | String | Header | true | The API Key for your app from the Developer Portal |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| accountNumber | String | Body | false | IBAN of the initiating party |
| transactionId | String | Body | true | Unique ID of the (released) payment |
| status | String | Body | false | The current status of the payment which is IN PROGRESS, SCHEDULED, EXECUTED, REJECTED after successful execution (PUT) |
POST Batch
POST /v1/payments/batch
This operation will post a batch payment for further authorization by a commercial account holder in Internet Banking or Access Online, see Authorization and Tutorials for details. The batch payment can be sent in as SCT (PAIN.001.001.03) or SDD (pain.008.001.02) XML file. For more information, see the ABN AMRO SEPA implementation guidelines.
When delivering payment towards ABN AMRO through this API, the payment must be compressed first using GZIP format. The binary file must be posted BASE64 UTF-8 encoded.
For a commercial client SCT files can be sent in for authorization. For SDD files, the account holder must have a direct debit contract. When an account is not commercial, or a SDD contract is missing, the file is rejected and is not shown in Internet Banking or Access Online for authorization.
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 | The API Key for your app from the Developer Portal |
| sepaBatchPaymentInstruction | Object | Body | true | A group identifying the batch file to be uploaded |
| fileName | String | Body | true | Specifies the name of the batch file. A unique filename is recommended |
| fileData | String | Body | true | A GZIP compressed SCT or SDD Batch file. The binary GZIP file must be BASE64 encoded using UTF-8 |
The maximum number of transactions is 99.999. Multi-level — multiple batches in same file — or non-SEPA batches are not supported. For more information, see ABN AMRO SEPA implementation guidelines.
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| hash | String | Body | false | SHA256 hash is calculated by ABN AMRO on the uncompressed file, and can be used to check integrity of the file posted. Hash is returned for a positive status only |
| id | String | Body | false | Unique ID generated for identification of batch. ID is returned for a positive status only |
| status | String | Body | false | The status of the posted batch which is 'RECEIVED' or 'REJECTED' |
Note: There is no duplicate check for batch files, batches in the files, or transactions in the batches. The responsibility for duplicate checking is with the person or persons who are completing authorizations in Online Signing.
Status:
- When a status is 'RECEIVED' the batch file has been sent to Internet Banking or Access Online, where the account holder can authorize the execution of the batch.
- When a status is 'REJECTED' there is a syntax error in the XML file that must be corrected. If you cannot find the error, contact ABN AMRO for help.
GET Consentinfo
GET /v1/consentinfo
This operation provides information regarding the authorization to a resource that an access token provides. The access token represents the consent granted by the account holder, or resource owner, to an account or resource. The information returned contains information about the granted scopes, selected account number or Transaction ID.
The use-case of Consent Information is depicted in the following sequence diagram.
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 |
Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| iban | String | Body | false | The IBAN/account number associated with the access token |
| transactionId | String | Body | false | The Transaction ID associated with the access token for registered payments. It is 'null' if an access token is not for payment |
| scopes | String | Body | false | The scopes associated with the access token |
| valid | Number | Body | true | Time that the token is valid |
Note: You can store the IBAN, transactionId and scopes for your own administration and for access to the API.
Error Response & 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, see Error handling.
Error Response Attributes
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| code | String | Body | true | The code of the error |
| message | String | Body | true | The human readable error message |
| reference | String | Body | true | Reference on 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'. For more generic categories, see Error handling |
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, see Error Codes in Get Started.
| 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 is greater than 70 characters |
| 400 | MESSAGE_BAI561_0071 | Counter party account number is BLANK |
| 400 | MESSAGE_BAI561_0072 | REMITTANCE info field length is greater 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 5xx error for POST, PUT or GET you can retry. If the error persists contact the bank |
Characterset
For SEPA payments and cross-border payments the character set 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 the clearing system.
Additional info
- There is no duplicate check on any of the payment methods.
- A response is always sent. Ensure that your application does not time-out.
- If a 5xx or time-out occurs, do not assume the payment failed:
- If POST fails, try to post the payment again.
- If PUT fails, try to check the status of the payment using GET. If the status is still 'AUTHORIZED', try to release again. If the status changes to 'INPROGRESS', 'SCHEDULED', or 'EXECUTED' the execution is succeeded. If the status is 'REJECTED', contact the bank.
- If GET fails, retry later.
- If reposting, avoid using short retry periods to keep out of rate limiting scenarios.
Previous releases
v1.01
- Sandbox is now live
- Updated OAuth2 in the YAML file
- Updated documentation for the Sandbox environment
- Minor improvements