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 know the main changes.

You'll find comprehensive guides and documentation to help you start working with Bridge 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 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): this field is an open value that will be available on the payment request
  • bank_id: id of the bank of your client

  • client_reference (optional): a reference to help you match the payment request to your system

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

    • amount
    • currency
    • label: the label of the payment which will be displayed on bank interfaces
    • 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): a reference to help you match the transaction to your system
    • end_to_end_id (optional): this field is an open value that will be available on the payment request and will be sent to the bank

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 to pass reconciliation information from end to end.

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
    }'

The answer of the call will give :

  • 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"
}

Known what to display in your callback URL pages

Here is a detailed user journey with when and how your user might be redirected to your callback URLs:

Detailed payment initiation user journeyDetailed payment initiation user journey

Detailed payment initiation user journey

🚧

Important: your users can quit before accessing your callback URL

When integrating our solution, please keep in mind that your users can quit at any step and then they might not be redirected to your callback URL (then you won't be able to get their payment status at this step). We recommend you to develop a job to check payments status regularly thanks to the endpoint List payment requests. This endpoint will list every payment request

When your users access our Bridge URL right after you call you created a payment request, we do several verifications before redirecting them to the 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?
Maybe a user has already confirmed the payment with success and the payment request status should be PDNG, ACSP or ACSC. In this case, your users will be redirected to your unsuccessful callback URL with a parameter reason=already_done.

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


If every answer to the last 3 questions is "No", then the users will be redirected to the bank interface. Here, 2 cases can happen.

The users click on a link "Exit" 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.

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

📘

Statuses are detailed later in Payments statuses.

Updated 6 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.