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:

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

  • (first_name AND last_name) OR company_name: name of the user who will initiate the payment
  • 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
  • currency (EUR)
  • 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": {
    "first_name": "Thomas",
    "last_name": "Pichet",
    "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": {
                "first_name": "Test",
                "last_name": "Name",
                "iban": "FR2310096000301695931368H67"
        },
        "client_reference": "12345678-AZERTY",
        "end_to_end_id": "12345678-AFERS"
      ],
      "user": {
         "first_name": "Firstname",
         "last_name": "Lastname",
         "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",
      "client_reference": "12345678-AZERTY",
      "end_to_end_id": "12345678-AFERS",
      "execution_date": "2022-08-30",
      "beneficiary": {
        "first_name": "Test",
        "last_name": "Name",
        "iban": "FR2310096000301695931368H67"
      }
    }
  ],
  "user": {
    "first_name": "Thomas",
    "last_name": "Pichet",
    "external_reference": "AEF142536-890"
  },
  "client_reference": "12345678-AZERTY",
  "bank_id": 6
}'

Response :

• id: id of the payment request
• consent_url: bank URL to initiate the payment

{
  "id": "e959dccd632c49d7922a766e946ad9e9",
  "consent_url": "https://pay.bridgeapi.io/payment/9d8687e4400c4efa87f4b61cc3da3bd1/initiate"
}

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:

🚧

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 you to integrate our payments webhooks to be updated on payment request statuses.

When your users click on the consent url to be redirected to our hosted page. Bridge does several security checks 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 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, RJCT or CANC.

📘

Statuses are detailed in Payment requests and transactions statuses