Payments

Payment Initiation

Initiate payments and retrieve information.

Tutorials Single Payments

This tutorial describes how to connect an application to the Payment Initiation APIs for single payments in the sandbox environment.

Important: You must have a PSD2 license to access production accounts.

Notes:
- For information on test data see Sandbox
- For information on the API operations see Technical
- For tutorials on batch payments click here

Onboarding

For access to the sandbox it is not required to be onboarded. For information on how to get access to ABN AMRO accounts in production see Overview.

Payment Initiation uses OAuth as authorization method to get access to an account. Click here for information.

You can follow the step-by-step tutorial below to learn how to access the APIs in sandbox environment and production alike.

1. Request an Access Token for Payment Registration

First you need to request an access token to register a payment:

Sample Request SEPA Payment
curl -X POST -k https://auth-sandbox.connect.abnamro.com:8443/as/token.oauth2 \
-v \
--cert TPPCertificate.crt \
--key TPPprivateKey.key \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=TPP_test&scope=psd2:payment:sepa:write psd2:payment:sepa:read'
Sample Request Crossborder Payment
curl -X POST -k https://auth-sandbox.connect.abnamro.com:8443/as/token.oauth2 \
-v \
--cert TPPCertificate.crt \
--key TPPprivateKey.key \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=TPP_test&scope=psd2:payment:xborder:write'
Sample Request Standing Order Payment
curl -X POST -k https://auth-sandbox.connect.abnamro.com:8443/as/token.oauth2 \
-v \
--cert TPPCertificate.crt \
--key TPPprivateKey.key \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=TPP_test&scope=psd2:payment:recurrent:sepa:write'
Request Attributes
Attribute Description
grant_type Indicates which type of authorization is used, it must contain 'authorization_code'
scope Indicates for which scope authorization is requested. For more information see Technical
client_id In the sandbox environment, use TPP_test as client_id. In production you will receive a client_id from ABN AMRO

-k is used in the sandbox environment to overrule the certificate check because a self-signed certificate is used.

Sample Response
{
  "token_type": "Bearer",
  "access_token": "X1PTWZre0fnW72l263yrhAWB2FDwx3tg",
  "expires_in": 7199
}

For more details you can refer to the OAuth page.

2. Register Payment

Now you can register the payment which the account holder can authorize in the next step. You can register a SEPA payment, a crossborder payment which is a NON EUR payment or EUR payment outside EMU, or a standing payment order in EUR. For batch payments see Tutorial Batch

Sample Request SEPA Payment
curl -X POST -k https://api-sandbox.abnamro.com/v1/payments  \
-v \
-H 'accept: application/json'  \
-H 'authorization: Bearer X1PTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'content-type: application/json'  \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-d '{
"initiatingpartyAccountNumber": "NL62ABNA9999841479",
"counterpartyAccountNumber": "NL12ABNA9999876523",
"amount": 149.99,
"counterpartyName": "John Doe",
"remittanceInfo": "Payment of invoice 123/01"
  }'
Sample Request structured SEPA Payment
curl -X POST -k https://api-sandbox.abnamro.com/v1/payments  \
-v \
-H 'accept: application/json'  \
-H 'authorization: Bearer UTUZnSKhYEYhX9qWl03epLVC3jyD' \
-H 'content-type: application/json'  \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-d '{
"initiatingpartyAccountNumber": "NL62ABNA9999841479",
"counterpartyAccountNumber": "NL12ABNA9999876523",
"amount": 149.99,
"requestedExecutionDate": "2020-01-30",
"counterpartyName": "John Doe",
"structuredRemittanceInfo": {
  "issuer": "CUR",
  "reference": "12345"
    }
  }'
Sample Request SEPA Standing Order
curl -X POST -k https://api-sandbox.abnamro.com/v1/payments/standingorder  \
-v \
-H 'accept: application/json'  \
-H 'authorization: Bearer X1PTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'content-type: application/json'  \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-d '{
"startDate": "2019-07-30",
"endDate": "2020-06-30",
"frequency": "MONTHLY",
"payment": {
  "initiatingpartyAccountNumber": "NL62ABNA9999841479",
  "counterpartyAccountNumber": "NL12ABNA9999876523",
  "counterpartyName": "John Doe",
  "amount": 149.99,
  "remittanceInfo": "Monthly payment"
    }
  }'  
Request Attributes SEPA payments
Attribute Description
authorization The access token that is used to register a payment. The token is received in the previous step, and must be passed as bearer token
API-Key The consumer key for your sandbox application. This is obtained from the developer portal
initiatingpartyAccountNumber 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
requestedExecutionDate 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 Information for the beneficiary about the payment. This type of information is 'unstructured'. A maximum of 140 characters is allowed
structuredRemittanceInfo A group identifying structured remittance information. Either unstructured remittanceInfo can be used or structuredRemittanceInfo
issuer 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 The structured remittance information
startDate Start date of the standing order in the format yyyy-mm-dd. Must be today or maximum of 30 days in future
endDate Optional end date of the standing order order, in the format: yyyy-mm-dd. If left blank, the end date is indefinite. When filled it must be >= startDate
frequency The 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'

For a complete listing of attributes, see Technical.

Note: Store the transactionId, it is used to check the account holder authorization and to execute the authorized payment.

Sample Request Xborder Payment
curl -X POST -k https://api-sandbox.abnamro.com/v1/payments/xborder \
-v \
-H 'accept: application/json'  \
-H 'authorization: Bearer X1PTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'content-type: application/json'  \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-d '{
  "initiatingParty": {
     "accountNumber": "NL62ABNA9999841479",
     "accountCurrency": ""
  },
  "counterParty": {
   "name": "John Doe",
   "accountNumberType": "IBAN",
   "accountNumber": "NL12ABNA9999876523",
   "bankIdentifierType": "SWIFTBIC",
   "bankIdentifier": "ABNANL2A"
  },
  "amount": 3.78,
  "currency": "USD",
  "chargesBearer": "SHA",
  "remittanceInfo": "A text with details of the payment"
  }'
Request Attributes XBorder
Name Description
accountNumberType Indicates which type of accountNumber is being used, either IBAN or BBAN, BBAN is used for domestic/basic formatting
bankIdentifierType Indicates the type of bankIdentifier used; SWIFTBIC, for a BIC; UKSORTCODE, for a UK sortcode; or FEDWIRE, for a US bankcode
chargesBearer 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
Sample Response SEPA or XBorder
{
  "accountNumber": "NL62ABNA9999841479",
  "transactionId": "321463282363179XX",
  "status": "STORED"
}'

Note: Store the transactionId, it is used to check the account holder authorization and to execute the authorized payment.

Request consent by directing the account holder to the following url through browser or mobile banking app:

Sample Request for Consent SEPA Payment
https://auth-sandbox.connect.abnamro.com/as/authorization.oauth2?scope=psd2:payment:sepa:write+psd2:payment:sepa:read&client_id=TPP_test&transactionId=123&response_type=code&flow=code&redirect_uri=https://localhost/auth&bank=NLAA01&state=Paymentreference123
Sample request for consent standing order payment
https://auth-sandbox.connect.abnamro.com/as/authorization.oauth2?scope=psd2:payment:recurrent:sepa:write&client_id=TPP_test&transactionId=123&response_type=code&flow=code&redirect_uri=https://localhost/auth&bank=NLAA01&state=Paymentreference123
Sample request for consent xborder payment
https://auth-sandbox.connect.abnamro.com/as/authorization.oauth2?scope=psd2:payment:xborder:write&client_id=TPP_test&transactionId=123&response_type=code&flow=code&redirect_uri=https://localhost/auth&bank=NLAA01&state=Paymentreference123

All of the following examples will start the consent application. In the consent application, the ABN AMRO client can review the payment details that were registered by you and authorize the payment and check the status. The ABN AMRO client can either authorize or cancel the requested authorization. The ABN AMRO client can select an account number that is different from the account number in the registered payment when he is not authorized for that account. See (sandbox)for details.

Request Attributes
Attribute Description
scope Indicates for which scope consent is requested. This can be more than one scope. For more information see Technical
client_id In the sandbox environment, use TPP_test as client_id. In production you will receive a client_id from ABN AMRO
transactionId Unique ID that was generated during the registration of a payment
redirect_uri In production, it needs to be identical to url that was administered. In sandbox, you must use https://localhost/auth
bank Use this to select the bank where the account is held. When omitted reverts to NLAA01. See the table below for possible values
state Value that is returned to the calling party. This is used for session management. For example, this could be a reference number, informing you that you have consent on a transaction
Bank Description
NLAA01 Consent for an ABNAMRO account in NL or commercial ABN AMRO account in BE, GB or DE
BEPB01 Consent for an ABN AMRO Belgium Private Banking accounts
BEPB02 Consent for an ABN AMRO Belgium Independent Asset Manager accounts

For more information, see OAuth page.

In the response, you will get an OAuth code, which must be exchanged within 60 seconds for an Access token and refresh token in step 4.

Sample response
https://localhost/auth?code=9C6UrsGZ0Z3XJymRAOAgl7hKPLlWKUo9GBfMQQEs&state=Paymentreference123

Note: If consent is cancelled or not successful, the following error is returned: error_description=Unexpected+Runtime+Authn+Adapter+Integration+Problem.&error=server_error#. If this occurs, the registered payment is also cancelled and can no longer be authorized.

4. Exchange Access Code Token

Exchange the authorization code for an access token and a refresh token. The following is a CURL example:

Sample Request
curl -X POST -k https://auth-sandbox.connect.abnamro.com:8443/as/token.oauth2 \
-v \
--cert TPPCertificate.crt \
--key TPPprivateKey.key \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&client_id=TPP_test&code=9C6UrsGZ0Z3XJymRAOAgl7hKPLlWKUo9GBfMQQEs&redirect_uri=https://localhost/auth'
Request Attributes
Attribute Description
grant_type Indicates which type of authorization is used, it must contain 'authorization_code'
code The authorization code from the previous step
redirect_uri Is mandatory if a redirect_uri was used when requesting consent

For more details, refer to the OAuth.

Sample Response
{
  "access_token": "GPgYglX4sO1WhzfChx4tmjr4y7Qg",
  "refresh_token": "UHjIAzBZfLGh4dLm8cvEcH6d8BrOmCZXumOpznQBP1",
  "token_type": "Bearer",
  "expires_in": 7193
}

Note: Store the refresh token for later use. The access token is valid for 2 hours.

For the next step, you need an access token and transactionId to execute the authorized payment. There are two ways to find the transactionId:

  • Using state parameter in consent flow: when starting the consent process the state reference number can be linked to the transactionId in the response. If the state parameter is used Consent Information is not needed.
  • Using Consent Information the transactionId associated with the access token can be requested. Also scopes and account number are retured in the response.
Sample Request
curl -X GET -k https://api-sandbox.abnamro.com/v1/consentinfo \
-v \
-H 'accept: application/json' \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'authorization: Bearer GPgYglX4sO1WhzfChx4tmjr4y7Qg'
Request Attributes

Please see OAuth for details. Only parameters that need clarification are mentioned here.

Attribute Explanation
authorization The access token from step 4 for which you want to check the consent info
Sample Response
{
  "scopes": "payment:sepa:write payment:sepa:read",
  "iban": "NL62ABNA9999841479",
  "paymentReference": "8338L5812304793S0PD",
  "valid": "1543931986"
}

Store the transactionId (paymentReference) and payment scopes to execute the payment in the next step and to check status. The initiating account number (IBAN) can be used to link the tranaction to the account of the client.

6. Execute Payment

Next you can execute the stored payment that was authorized by the account holder in the previous steps.

Sample Request for SEPA Payment
curl -X PUT -k https://api-sandbox.abnamro.com/v1/payments/8338L5812304793S0PD \
-v \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'accept: application/json' \
-H 'authorization: Bearer GPgYglX4sO1WhzfChx4tmjr4y7Qg'
Sample Request for Standing Order
curl -X PUT -k https://api-sandbox.abnamro.com/v1/payments/standingorder/8338L5812304793S0PD \
-v \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'accept: application/json' \
-H 'authorization: Bearer GPgYglX4sO1WhzfChx4tmjr4y7Qg'
Sample Request for Xborder Payment
curl -X PUT -k https://api-sandbox.abnamro.com/v1/payments/xborder/8338L5812304793S0PD \
-v \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'accept: application/json' \
-H 'authorization: Bearer GPgYglX4sO1WhzfChx4tmjr4y7Qg'
Sample Response
{
  "accountNumber": "NL62ABNA9999841479",
  "transactionId": "8338L5812304793S0PD",
  "status": "EXECUTED"
}

If you used the state attribute with consent (in step 3), you can determine the initiating account number in the response here. For more information you can refer to the Technical.

Additional commands

Check Payment Status

If the status in the response for executing payment is not "EXECUTED" or "REJECTED" you can check at a later time what the status is using following sample request:

Sample Request for SEPA Payment
curl -X GET -k https://api-sandbox.abnamro.com/v1/payments/8338L5812304793S0PD \
-v \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'accept: application/json'  \
-H 'authorization: Bearer {your_access_token}'
Sample Response SEPA
{
  "accountNumber": "NL62ABNA9999841479",
  "transactionId": "8338L5812304793S0PD",
  "status": "AUTHORIZED"
}

Note: The status of payment should be "EXECUTED" or "STORED". Only in exceptional cases it may take several seconds before status is updated.

Cancel Payment

You can cancel a released payment that has future execution date.

Sample Request SEPA Payment
curl -X DELETE -k https://api-sandbox.abnamro.com/v1/payments/8338L5812304793S0PD \
-v \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'accept: application/json'  \
-H 'authorization: Bearer {your_access_token}'

Payments can be also cancelled by the account holder using Internet Banking or Access Online.

Refresh Access Token

If your access token expires you can request a new access token using the refresh token.

Sample Request
curl -X POST -k https://auth-sandbox.connect.abnamro.com:8443/as/token.oauth2 \
-v \
--cert {location_of_your_certificate} \
--key {location_of_your_private_key} \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&client_id=TPP_test&refresh_token=UHjIAzBZfLGh4dLm8cvEcH6d8BrOmCZXumOpznQBP1&scope=psd2:payment:sepa:write+psd2:payment:sepa:read'
Sample Response
{
  "access_token": "{mkwAngBIJtlL9TxxNhECHV4LaBBt}",
  "refresh_token": "{nLlBcohGqcAvs2iyQ4SAdenC5moqRh9y3NifBR3j04}",
  "token_type": "Bearer",
  "expires_in": 7193
}