Create a beneficiary

Before being able to perform an instant transfer, it is necessary to add the transfer recipient to one's list of beneficiaries.

The 🔗 Create a beneficiary endpoint is used in order to create and associate an external beneficiary account in order to perfom a Sepa Out operation.

• The BIC (Bank Identifier Code) is optionnal to add a beneficiary.

• The IBAN (International Bank Account Number) is mandatory to create the beneficiary

The following sequence diagram shows the API workflow to add a beneficiary :

sequenceDiagram
Title: Create a beneficiary
autoNumber
Actor User
Participant Partner
Participant XPO
Participant sca as SCA Partner
User ->> Partner : Add bank account
Partner ->> XPO : post /api/sca/v2.0/users/{appUserId}/beneficiary
XPO -->> Partner :return OK (201)
XPO ->> sca : Authentication<br/>requested
Partner -->> User : Authentication required<br/>{authenticationId}
sca -->> User : Authentication push notification request
User ->> sca : Authentication
sca -->> XPO : Authentication<br/>result
XPO -->> XPO : Authentication OK
XPO --) Partner : Callback 36<br/>{beneficiaryId}

❗️

When the add beneficiary feature is triggered by a manual action from an end user, it is mandatory to use the sca route to add a beneficiary as user authentication is required for security / compliance reasons.

Initiate an IP OUT

State diagram

stateDiagram
[*] --> Created: http 200 <br/> [synch]
Created --> Approved: *Internal status* <br/> transaction validated by <br/> the Xpollens Payment Decision system
Approved --> Completed : Checks between XPO and <br/> BPCE OK <br/> [Callback]
Approved --> Rejected : Checks between XPO and <br/> BPCE KO <br/>[Callback]
Completed --> [*]
Rejected --> [*]

IP OUT succeeded

sequenceDiagram

Title: Initiate an IP OUT
autoNumber
Actor User
Participant Partner
Participant XPO
Participant BPCE PS
User ->> Partner : Initiate an IP OUT
Partner ->> XPO : post /api/v3.0/sepa-instant-payments
XPO --) XPO : Check Beneficiary exist and active
XPO --) XPO : Check RefBip eligibility
XPO --) XPO : Check Payment allowed amount
XPO --) XPO : Create transaction

rect rgb(0, 255, 0, 0.1)
XPO ->> Partner :return OK http 201 (status:Created)
Note over XPO, BPCE PS: Checks between XPO and BPCE PS <br/> Need to answer in less than 8 secondes
XPO --) BPCE PS : Processing
BPCE PS --)XPO : IP accepted
XPO -->> Partner :Callback InstantPaymentCreatedOrUpdated {status:Completed, direction:debit}
end
Partner -->> User : Notification

🔗sepa-instant-payments

🔗Callback "InstantPaymentCreatedOrUpdated"

Succeeded during the post sepa-instant-payments Check Eligibility

Synchrone reponse

stateDiagram
[*] --> Created: http 200

Succeeded during the process between Xpollens and BPCE PS

Asynchrone reponse

stateDiagram
     Created --> Completed

IP OUT failed

sequenceDiagram
Title: Initiate an IP OUT
autoNumber
Actor User
Participant Partner
Participant XPO
Participant BPCE PS
User ->> Partner : Initiate an IP OUT
Partner ->> XPO : post /api/v3.0/sepa-instant-payments
XPO --) XPO : Check Beneficiary exist and active
XPO --) XPO : Check RefBip eligibility
XPO --) XPO : Check Payment allowed amount
XPO --) XPO : Create transaction 


alt Synchronous checks KO
        rect rgb(255, 0, 0, 0.1)
    XPO ->> Partner : http 40x
    Partner -->> User : Notification
        end
        
else Checks KO between XPO and BPCE PS
	rect rgb(0, 255, 0, 0.1)
			XPO ->> Partner : http 201
	end

   rect rgb(255, 0, 0, 0.1)
    Note over XPO, BPCE PS: Checks between XPO and BPCE PS <br/> Need to answer in less than 8 secondes
    XPO --) BPCE PS : Processing
    BPCE PS --)XPO : IP Rejected
    XPO -->> Partner : Callback InstantPaymentCreatedOrUpdated {status:Rejected}
   end
        
end

Partner -->> User : Notification

Failed during the post sepa-instant-payments

Failed during the process between Xpollens and BPCE PS

Recall IP

Recall IP OUT

How the partner can do a recall > Zendesk ticket to Xpollens' banking production department

Succeeded

sequenceDiagram
Title: Request an Recall IP OUT
autoNumber
Actor User
Participant Partner
Actor Xpollens/Production Bancaire
Participant XPO
Participant Counter part Bank

User --) Partner: Recall request
Partner --) Xpollens/Production Bancaire : Recall request (Zendesk)
Xpollens/Production Bancaire --) XPO : Recall Request 
XPO --) XPO : Check initial operation exist ( Debit )
XPO --) XPO : Check initial operation is successed / Completed
XPO --) XPO : Created recall transaction ( Created / Credit )
XPO --) Counter part Bank: Recall
Counter part Bank --) XPO : OK
Note over  XPO, Counter part Bank: 10 days to answer
XPO -->> Partner : Callback InstantPaymentCreatedOrUpdated {status:Completed, isRTransaction:true, direction:credit}
Partner -->> User: Notification

👍

Account credited

Failed

sequenceDiagram
Title: Request an Recall IP OUT
autoNumber
Actor User
Participant Partner
ACTOR Xpollens/Production Bancaire
Participant XPO
Participant Counter part Bank
Participant Partner

User --) Partner: Recall request
Partner --) Xpollens/Production Bancaire : Recall request (Zendesk)
 Xpollens/Production Bancaire ->> XPO : Recall Request
XPO --) XPO : Check initial operation exist ( Debit )
XPO --) XPO : Check initial operation is successed / Completed
XPO --) XPO :Created recall transaction ( Created / Credit )
XPO ->> Counter part Bank: Recall
Counter part Bank ->> XPO : KO
Note over  XPO, Counter part Bank: 10 days to answer
XPO -->> Partner : Callback InstantPaymentCreatedOrUpdated {status: Rejected, isRTransaction:true}
Partner -->> User: Notification

❗️

Account not debited

How to test

IP OUT

Only the ibans of unmocked environment pass the Luhn key checks and can be used.

POST /api/v2.0/users/{appUserId}/beneficiary

{
  "displayName": "Compte Xpollens 1",
  "iban": "FR7630001007941234567890185",
  "bic": "SMOEFRP1",
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Xpollens",
  "zipCode": "75001",
  "email": "[email protected]",
  "phoneNumber": "0123456789"
}

Response

{
[...]
"beneficiaryId": "YourBeneficiaryId",
[...]
}

POST /api/v3.0/sepa-instant-payments

{
  "sepaInstantPaymentId": "Ip-out-1",
  "accountId": "account-partner-reference",
  "creditor": {
    "beneficiaryId": "YourBeneficiaryId"
  },
  "amount": {
    "value": "5.00",
    "currency": "EUR"
  },
  "reference": "Reference-Ip-Out",
  "description": "Ip-Out-Description"
}

FAQ

Coming soon