Initiate your first payment

Payment Definition and Coverage

A payment within Bridge is technically represented as a Payment Request, which may consist of one or several Transactions. The capabilities of these payments depend on the specific features offered by the Bank involved. Here's an overview of the different payment types:

Create a payment request

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

Here are the fields you need to complete:

• successful_callback_url: The client will be redirected to this URL if the payment initiation is successful.

• unsuccessful_callback_url (optional): The client will be redirected to this URL if the payment fails.

• user

  • (first_name AND last_name) OR company_name: The name of the user who will initiate the payment.
  • external_reference (optional): We recommend filling this value with a unique ID that identifies your user. It helps Bridge optimize fraud detection by tracking how many payments have been initiated by a single user within a specific period.

• bank_id: The ID of the client's bank.

• client_reference (optional): A reference you can specify to optimize your payment request reconciliation. This reference will also be available when you retrieve the payment status using Bridge endpoints. There is a similar field in the transaction resource that can be used to reconcile individual transactions.

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

  • amount
  • currency (EUR)
  • label: The label of the payment, which will be displayed on both the payer's and payee's bank statements.
  • 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): Allows you to schedule payments for a specific date (up to 60 days in advance).
  • client_reference (optional): A reference you can specify to optimize your transaction reconciliation. This reference will also be available when you retrieve the payment status using Bridge endpoints. There is 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): A reference you can specify to optimize reconciliation. This reference will be sent to the bank and can be retrieved using Bridge endpoints, as well as from bank account aggregation.

You can determine which banks support these payment capabilities by checking the single_payment or bulk_payment field in the List banks resource.

🚧

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

While most banks allow you to initiate scheduled payments up to 60 days in advance, LCL and Société Générale Particuliers (IDs 152, 179, and 5) have restrictions. If you use LCL or Société Générale Particuliers, please set an execution date that is less than 30 days in advance.

📘

Reconciliation

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

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

To provide a clear understanding of when and how the payer will be redirected to your callback URLs, here's a detailed flow:

🚧

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

Keep in mind that your users have the option to close the tab displaying our hosted page at any time. Consequently, they may not always be redirected to your callback URL. To ensure your data remains synchronized, we recommend integrating our payments webhooks to stay updated on payment request statuses.

When your users click on the consent URL to be redirected to our hosted page, Bridge performs several security checks before redirecting the payer to their bank interface:

Has the link expired?
For security reasons, Bridge URLs are valid for 15 minutes. If the link has expired, 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 successfully, 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, resulting in a payment request status of ACTC, ACCP, RJCT, or CANC, the payer will be redirected to your unsuccessful callback URL with a parameter reason=already_failed.

If all the previous checks pass, the payer will be redirected to their bank interface.

Following that, two scenarios can occur:

Scenario 1: The Users Confirm the Payment, Payment Initiation Is a Success
In this case, the users will be redirected to your successful callback URL, and the payment request status should be either PDNG or ACSC.

Scenario 2: The Users Exit the Hosted Page by Clicking on the "Exit" Button or Confirm the Payment, but an Error Occurred
If the users exit the hosted page by clicking on "Exit" or if an error occurs during payment confirmation, they will be redirected to your unsuccessful callback URL. The payment request status should be either ACTC, RJCT, or CANC.

📘

For further information about payment request statuses, refer to Payment requests and transactions statuses