Tutorial

How the Pay By Invoice API works

Request onboarding using Request Production Access.
Provide your company name, contact information, method of connecting to this API (e-commerce plugin or directly), and other details.

Requirements

To use this API in a production environment, you must have the following:

A TLS certificate of one of the following types: Organization Validation (OV) or Extended Validation (EV) from Digicert, Quo Vadis, Sectigo or Entrust without wildcard options.
The organization name issued on the certificate must correspond to the name of the API contract holder.

Sandbox access

Note: The sandbox and production environments are not functionally identical. Most operations are identical except for the getPayByInvoiceOrderList operation. This operation returns a static list of orders on the sandbox environment.

To use the Pay By Invoice API sandbox environment, complete the following steps:

Register and create an account:
1. Click Sign up.
2. Enter your details, and click Create an account.
3. Developer Support will send you an activation link by email.
4. Click the activation link.
Create and register application:
1. Log in to your account.
2. In the left-side navigation click Apps.
3. Click Add app.
4. In the App name field, enter a name for your application.
5. In the APIs field, select Pay By Invoice, and click Add app.
Complete the How to use this API

Sandbox access details

Sandbox URL: https://api-sandbox.abnamro.com
Sandbox token URL: https://auth-sandbox.abnamro.com/as/token.oauth2

Use the following credentials for the sandbox:

Attribute	Value for sandbox
client_id	PBI_test_client
API-Key	The API Key for your production application on the Developer Portal

Note: Please contact API Provider team to get onboarded on the sandbox.

To provide feedback on this API, see Contact.

Production access

Follow requirements given below to use this API in a production environment.

To get access to production:

Log in to ABN AMRO Developer Portal.
In the left-side navigation, click Apps.
Click Request Production Access.
Select the API category that you want to request production access for.

Note: It is not possible to request production access for multiple API categories in one request.
Fill in the form, and click Submit.
You receive a confirmation email and ticket-ID.
ABN AMRO Developer Support validates the form.
When the form is validated and the setup is complete, ABN AMRO Developer Support contacts you and supplies you with a client_id.
A new app is added in Apps. This new app contains your API key.

Production access details

Production URL: https://api.abnamro.com
Production Token URL: https://auth-mtls.abnamro.com/as/token.oauth2:443

Use the following credentials for production:

Attribute	Value for Production
client_id	As supplied to you by ABN AMRO
API-Key	The API Key for your production application on the Developer Portal

Certificates:

Certificate files:
Certificate file : Your OV or EV SSL certificate
Private key : Your private key

How to use this API

Below you will find a description of a typical flow of how the different operations are executed. However, you might want to deviate from this order depending on your setup.

Step 1: Request an access token

In this step, the OAuth 2.0 client credentials flow is used to obtain access to the Pay By Invoice API.

Request attributes

You must specify the scope for the operation that is to be authorized. The possible scopes are described in the table below.

Operation	Request for scope
Select company	pay-by-invoice:global:all
Create order intent	pay-by-invoice:global:all
Create order	pay-by-invoice:global:all
Confirm order	pay-by-invoice:global:all
Handling orders	pay-by-invoice:global:all

The table below defines the usage of attributes in a request.

Attribute	Value
client_id	PBI_test_client
API-Key	The API Key for your application on the Developer Portal

Certificates

Certificate files
Download public certificate: Download
Download private key: Download

Sample request

Request an access token using the following sample:

```shell
 curl -X POST \
 https://auth-mtls-sandbox.abnamro.com/as/token.oauth2 \
 --cert CertificateCommercial.crt \
 --key PrivateKeyCommercial.key \
 -d 'grant_type=client_credentials&client_id=PBI_test_client&scope=pay-by-invoice:global:all'
```

Sample response

```json
{
  "token_type": "Bearer",
  "access_token": "X1PTWZre0fnW72l263yrhAWB2FDwx3tg",
  "expires_in": 3599
}
```

Step 2: Select company

This operation helps to find the company in the register and find the companyId, the parameter that can be further used in the next step to get the detailed information about the specific company.

Execute Search Company operation to search for companies by name or official registry IDs.
Execute Get Company operation using the Company Id parameter that was received in the above step. This operation will return the full details of a company including the company national identifier, type, address, and canonical Id.

Using above mentioned checks one can ensure that the user places an order on behalf of the correct organization. It enables an improved user experience and lowers the friction.

Step 3: Create order intent

Use this operation to check upfront whether a payment method will be accepted for the buyer (Order intent)

Execute Create Order Intent operation. It performs credit check of your buyer during the checkout to figure out if the invoice payment is applicable as a payment method for the buyer.
Collect the trackingId from the response of the Create Order Intent operation. It should be used to connect the order intent with the actual order being placed by the buyer.

Step 4: Create order

Create an order by building a request body containing all required elements and executing the Create Order operation.

Execute Create Order operation to create a new order in the system.
Read the state and status of the order response.
Check if the status is APPROVED.
Check if the state is UNVERIFIED, and redirect the user to the paymentUrl.

After completing the verification, the user is redirected back to your order confirmation page.

Step 5: Confirm order

Execute the Confirm Order operation to confirm that the user has arrived at the order confirmation page.

Step 6: Handling orders

In addition to company lookup and order creation and confirmation, the existing order can also be handled with executing the following operations:

Cancel order
Update order
Fulfill order
Refund order

Cancel order

Execute the Cancel Order operation to cancel a specific order.

Update order

Execute the Update Order operation with a specified request body to update an order

Fulfil order

Execute the Fulfil Order operation with a specified request body to fulfil all line items of an order.

Note: Include a request body in order to do a partial fulfillment.

Refund order

Execute the Refund Order operation to refund a specific order.

Note: Include a request body in order to do a partial refund.

Pay By Invoice 1.1.0