Bridge API Documentation

Bridge Documentation

Welcome to our API documentation!

We're happy to share with you our new API 2021 version! Please check our Product Changelog to see the main updates.

You'll find comprehensive guides and documentation to help you start integration Bridge API as quickly as possible, as well as support if you get stuck.

Let's jump right in!

Get Started

Initiate your first Payment

Payment definition and coverage

A Payment is technically a Payment Request composed by one or several Transactions.

Depending on the Bank capabilities, you will be able to proceed different types of payments:

Capabilities

Description

single_payment

Payment request with one transaction (standard wire transfer)

single_payment_scheduled

Payment request with one transaction with a specific execution date (scheduled wire transfer)

bulk_payment

Payment request with several transactions (standard wire transfers)

Create a payment request

To initiate a payment you just need to create a Payment Request that will generate a consent_url. This URL will redirect your client (the payer) to his bank interface to validate the payment.

The fields to complete are :

  • successful_callback_url: the client will be redirected on this URL if the payment initiation is a success

  • unsuccessful_callback_url (optional): the client will be redirected on this URL if the payment is a failure

  • user

    • name: name of your client which will initiate the payment (first name and last name or company name)
    • external_reference (optional): We recommend to fill this value with a unique id that identify your user. It will be use by Bridge to optimize fraud detection (i.e how many payments / period of time have been initiated for a single user)
  • bank_id: id of the bank of your client

  • client_reference (optional): Reference that you can specify to optimize your payment request reconciliation that will also be available when you get the payment status later on using Bridge endpoints. There is also a similar field in the transaction resource that can be used to reconcile a single transaction.

  • transactions: an array with the details of the payment(s) you want the customer to initiate

    • amount (35 000€ maximum, feel free to contact us if you need a different limit)
    • currency
    • label: the label of the payment which will be displayed on the payer and payee bank statement
    • beneficiary (optional if every payment must be sent to the same beneficiary, please check the Manage beneficiaries chapter for this specific topic)
      • name: name of the payment beneficiary
      • iban: iban of the beneficiary
    • execution_date (optional): to schedule the payments to a specific date (up to 60 days in advance)
    • client_reference (optional): Reference that you can specify to optimize your transaction reconciliation that will also be available when you get the payment status later on using Bridge endpoints. There is also a similar field at the root of the payment request resource that can be used to reconcile a payment request.
    • end_to_end_id (optional): Reference that you can specify to optimize reconciliation. This reference will be sent to the bank and can be retrieved using Bridge endpoints but also from bank account aggregation.

You can check which banks support the Payments thanks to the capabilities single_payment or bulk_payment field on the List banks.

🚧

Scheduled payments - Warning for LCL and Société Générale Particuliers

Every bank available allows you to initiate scheduled payments up to 60 days in advance, except for LCL and Société Générale Particuliers (id 152, 179 and 5). If you use LCL or Société Générale Particuliers, please set an execution date inferior to 30 days in advance.

📘

Reconciliation

Please note that all banks don't display the end_to_end_id on the beneficiary's interface. You may use the label and the two fields client_reference to optimize reconciliation.

curl 'https://api.bridgeapi.io/v2/payment-requests' \
    -X POST \
    -H 'Bridge-Version: 2021-06-01' \
    -H 'Client-Id: MY_CLIENT_ID' \
    -H 'Client-Secret: MY_CLIENT_SECRET'
    -H 'Content-Type: application/json' \
    -d '{
      "successful_callback_url": "https://my-callback-url.com:8080/pay/success",
      "unsuccessful_callback_url": "https://my-callback-url.com:8080/pay/error",
      "transactions": [
       {
         "amount": 99.5,
         "currency": "EUR",
         "label": "Payment label",
         "client_reference": "12345678-AZERTY",
         "end_to_end_id": "12345678-AFERS"
       }
      ],
      "user": {
         "name": "Firstname Lastname",
         "external_reference": "AEF142536-890"
      },
      "client_reference": "12345678-AZERTY",
      "bank_id": 6
    }'
curl 'https://api.bridgeapi.io/v2/payment-requests' \
    -X POST \
    -H 'Bridge-Version: 2021-06-01' \
    -H 'Client-Id: MY_CLIENT_ID' \
    -H 'Client-Secret: MY_CLIENT_SECRET'
    -H 'Content-Type: application/json' \
    -d '{
      "successful_callback_url": "https://my-callback-url.com:8080/pay/success",
      "unsuccessful_callback_url": "https://my-callback-url.com:8080/pay/error",
      "transactions": [
       {
        "amount": 99.5,
        "currency": "EUR",
        "label": "Payment label",
        "beneficiary": {
              "name": "Firstname Lastname",
            "iban": "FR1814508000703595363636L75"
        },
        "client_reference": "12345678-AZERTY",
        "end_to_end_id": "12345678-AFERS"
      ],
      "user": {
         "name": "Firstname Lastname",
         "ip_address": "0.0.0.0",
         "external_reference": "AEF142536-890"
      },
      "bank_id": 6
    }'
curl 'https://api.bridgeapi.io/v2/payment-requests' \
    -X POST \
    -H 'Bridge-Version: 2021-06-01' \
    -H 'Client-Id: MY_CLIENT_ID' \
    -H 'Client-Secret: MY_CLIENT_SECRET'
    -H 'Content-Type: application/json' \
    -d '{
      "successful_callback_url": "https://my-callback-url.com:8080/pay/success",
      "unsuccessful_callback_url": "https://my-callback-url.com:8080/pay/error",
      "transactions": [
       {
         "amount": 99.5,
         "currency": "EUR",
         "label": "Payment label",
         "execution_date": "2021-10-30",
         "beneficiary": {
             "name": "Firstname Lastname",
           "iban": "FR1814508000703595363636L75"
         },
         "client_reference": "12345678-AZERTY",
         "end_to_end_id": "12345678-AFERS"
      ],
      "user": {
         "name": "Firstname Lastname",
         "ip_address": "0.0.0.0",
         "external_reference": "AEF142536-890"
      },
      "bank_id": 6
    }'

Response :

  • id: id of the payment request
  • consent_url: bank URL to initiate the payment
{
  "id": "e959dccd632c49d7922a766e946ad9e9",
  "consent_url": "https://api.bridgeapi.io/v2/payment-requests/e959dccd632c49d7922a766e946ad9e9/link"
}

What to display when your callback URLs are called

Here is a detailed flow specifying when and how the payer will be redirected to your callback URLs:

Detailed payment initiation user flowDetailed payment initiation user flow

Detailed payment initiation user flow

🚧

Important: the payer can close our hosted page without your callback urls being called

When integrating our solution, please keep in mind that your users can close the tab displaying our hosted page anytime and consequently might not be redirected to your callback URL. To keep your data in sync, we recommend regularly check your payments status thanks to the endpoint List payment requests. This endpoint lists every payment request.

Update: Webhooks are currently being developed to ease this step.

When your users click on the consent url to be redirected to our hosted page. Bridge do several security check before redirecting the payer to his bank interface:

Has the link expired?
For security reasons, Bridge URLs are valid for 15 minutes. If it has expired already, your users will be redirected to your unsuccessful callback URL with a parameter reason=expired.

Has the payment already been confirmed?
If a user has already confirmed the payment with success and the payment request status is PDNG, ACSP or ACSC, the payer will be redirected to your unsuccessful callback URL with a parameter reason=already_done.

Has the payment already failed or been rejected?
If a user has already confirmed the payment and it failed, the payment request status is either ACTC, ACCP, RJCT or CANC. In this case, the payer will be redirected to your unsuccessful callback URL with a parameter reason=already_failed.


If all the previous check are all OK, then the payer will be redirected to his bank interface.

After that, 2 scenarii can happen.

The users confirm the payment, payment initiation is a success
Then the users will be redirected to your successful callback URL. Payment request status should be either PDNG, ACSP or ACSC.

The users exit the hosted by clicking on "Exit" button or confirm the payment but an error occurred
Then the users will be redirected to your unsuccessful callback URL. Payment request status should be either ACTC, ACCP, RJCT or CANC.

📘

Statuses are detailed later in Payments statuses.

Updated 27 days ago


Initiate your first Payment


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.