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
- (
first_name
ANDlast_name
) ORcompany_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 initiateamount
currency
(EUR)label
: the label of the payment which will be displayed on the payer and payee bank statementbeneficiary
(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 beneficiaryiban
: 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 thelabel
and the two fieldsclient_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 requestconsent_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:

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 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
Updated 5 months ago