Payments

Payment Initiation

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.

OAuthConsentInfoAI.svg

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