Payments

Payment Initiation

Initiate payments and retrieve information.

Tutorials Batch Payments

This tutorial describes how to connect an application to the Batch Payment Initiation API 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 single 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 Batch API in sandbox environment and production alike.

Request consent to send a batch payment by directing the account holder to the following url:

Sample Request for Consent for a Batch SCT Payment
https://auth-sandbox.connect.abnamro.com/as/authorization.oauth2?scope=psd2:payment:batchsct:write&client_id=TPP_test&response_type=code&flow=code&redirect_uri=https://localhost/auth&bank=NLAA01&state=Paymentreference123
Sample Request for Consent for a Batch SDD Payment
https://auth-sandbox.connect.abnamro.com/as/authorization.oauth2?scope=psd2:payment:batchsdd:write&client_id=TPP_test&response_type=code&flow=code&redirect_uri=https://localhost/auth&bank=NLAA01&state=Paymentreference123

In the consent application the account holder can select the account for which they want to give for batch payments consent on.

Request Attributes
Attribute Description
scope The scope attribute is used for which scopes access is needed. For batch this can be psd2:payment:batchsct:write and/or psd2:payment:batchsdd:write. When sending in Direct Debits, the account holder must have a direct debit contract with ABN AMRO. See also Technical
client_id In the sandbox environment, use TPP_test as client_id. In production you will receive a client_id from ABN AMRO
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 ABNAMRO account in NL or commercial ABN AMRO account in BE, GB or DE
BEPB01 Consent for ABN AMRO Belgium Private Banking accounts
BEPB02 Consent for ABN AMRO Belgium Independent Asset Manager accounts

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

For more details you can refer to the OAuth page.

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

Note:

  • The access code is valid for 60 seconds only.
  • When consent is cancelled or unsuccessful, an the following error is returned: error_description=Unexpected+Runtime+Authn+Adapter+Integration+Problem.&error=server_error#.

2. Exchange Access Code Token

Next the authorization code needs to be exchanged for an access token and a refresh token. Below 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'

The code in the example needs to be replaced with the code received in the response from the sandbox as described in step 1.

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 When redirect_uri was used for requesting consent

For more details, refer to the OAuth.

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

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

Using Consent Info you can check the account number for which you received consent.

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
Attribute Explanation
authorization The access token from step 2 for which you want to check the consent info
Sample Response
{
  "scopes": "psd2:payment:batchsct:write psd2:payment:batchsdd:write",
  "iban": "NL62ABNA9999841479",
  "paymentReference": null,
  "valid": "1543931986"
}

Store the IBAN and scopes for your own adminstration and to send in the batch payment file in the next step.

For more information see OAuth.

4. Post Batch

Post the batch file to be processed. You can download a sample SCT file here, and a sample SDD file here.

  1. GZIP the SCT or SDD file.
  2. Encode the file in BASE64 using UTF-8.
  3. Post the batch file as in the sample below.
Sample Request SCT Batch
curl -X POST -k https://api-sandbox.abnamro.com/v1/payments/batch  \
-v \
-H 'accept: application/json'  \
-H 'authorization: Bearer X1PTWZre0fnW72l263yrhAWB2FDwx3tg' \
-H 'content-type: application/json'  \
-H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
-d '{ "sepaBatchPaymentInstruction": {
      "fileName": "SampleSCT.xml.gz", 
      "fileData": "H4sIAAAAAAAAA7VVUXOiMBB+91c4vGsgtmoZTEdR77yqdZTe3JtDSURmJHohVnu//pagVSG093KZUch+u9/usruJ83iMN9U3JpJoyzuGVTeNKuPBlkY87Bgv3rDWNh5Jxelvg33MuARtnnSMveB2lGztRFL1xKaJsS1ZsLaPCbV3fsTrpmllv4ZRUWYARR1jLeXORuhwONQPjfpWhAiMLfRrMl4Eaxb7tYgn0ucBM0ilCstxExkLl0pPrEY8kjwTK+ib2H2n4iJQwkkSjigx02U5KNvdariC9aUXE2xaDzWzUcOWZ7Xse2zjloPO4K3J9PV55R0TAozn1xynFJvFPiZWHZtActrd6qThhzP5TpxpTJ42Ppfc92NgzCuiD81LriifrDOL5YivcqaZEFJeuN5y4C0n3vLHnrMlhsg/sILJRFLizYdKJX3/D8kDs7crxKugxVswftsUgYwbUhnMukBLNaZIZ6vS0Dhz5uw3HRwDyfvyqvgOupbfWvRfpdC4hYr12Wsk2V7oyle0UkTdIJAasnxBLkCvOyXTcRN3e9PuA6z2nXXXeoD2SAHNxyiUFundZtGEumCGER/BAPLSoHojl6TxTMcYipLuNIGUsZwCynt23LUIe4IsxoOfUOhsk9NQB4B31HdQ2tllAQ849bbwBwrP/A+rCrZiAo6yiNlVCzfu7psOutLRZFPC7nRjzRdUSJo8BbjqBu8dY/AyN06zcQZ0bvRiSFxfKoV+VS6l9A8lyyL4jC0dwLKmSZESThgOOFFpyahciMsy146Mgr8aG+syNq3mPW6UjU0Wwycp66d2rjl9bxReEikombNVPT1q4BpsQ6NlQo0nHZ3yX+z680F+uh9R8YKEMTvd1+Qvryawd+EHAAA="
      }
    }'

To upload a SDD file, add a SDD file the fileData field in the sample above.

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
sepaBatchPaymentInstruction Object Body true A group identifying the batch file to be uploaded
fileName String Body true Specifies the name of the batch file. Recommended to use a unique filename
fileData String Body true A GZIP compressed SCT or SDD Batch file. The binairy GZIP file must be BASE64 encoded using UTF-8
Sample Response
{
    "sepaBatchPaymentInstruction": {
        "id": "9106O2454217947S0PD;NL62ABNA9999841479",
        "hash": "479740c87d4cf4a912f15218665b2ed48c38d19d3c6694f2581c4654b40711ef",
        "status": "RECEIVED"
    }
}
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 only returned for positive status
id String Body false Unique id generated for identification of batch. Id is only returned for positive status. You should store the id since it is later needed.
status String Body false The status of the posted batch which is RECEIVED or REJECTED

Status:

- When a status is 'RECEIVED' the batch file has been sent to to Internet Banking / Access Online, where the account holder can authorize the execution of the batch.

- When a status 'REJECTED' there is a syntax error in the XML file that needs to be corrected. If you cannot find the error contact ABN AMRO for help.

5. Execute Payment

The batch payment file is available for the commercial accountholder in Internet Banking / Access Online for authorization. First the account holder needs to login Internet Banking or Access Online. Batch payments can only be authorized for commercial accounts. Also Access Online users need to have Batch Autorization role(s) to authorize execution of the SCT or SDD batch file.

Notes:

- For execution of direct debits the client must have a contract.

- A method for retrieving the status of the batch payment is not yet available. You can check execution of the payment by retrieving Account Information for real-time information on the booking of the batch payment. The account holder can check the status in Internet Banking or Access Online.

6. 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:batchsct:write+psd2:payment:batchsdd:write'
Sample Response
{
  "access_token": "{mkwAngBIJtlL9TxxNhECHV4LaBBt}",
  "refresh_token": "{nLlBcohGqcAvs2iyQ4SAdenC5moqRh9y3NifBR3j04}",
  "token_type": "Bearer",
  "valid": 7193
}