Definition

📘

A Top-Up card is a way for your customer to credit an account directly from a debit/credit card.

Main steps

1- Collect the card detail through Payplug hosted fields

2- Collect the payer's details through your form

3- Create the HF Token

4- Process the request

5- Controls are performed on the payer’s details and their consistency with the card information

6- Receive the final result through the webhook

Top-up state diagram

stateDiagram
[*] --> Approved: Top-up authorisation, waiting for 3DS checks
Approved --> Completed : 
Completed --> Refund : top-up refunded
Approved --> Rejected: 3DS KO or missing, <br/> transaction refused,  <br/> ... 
Refund --> [*]
Rejected --> [*]
Completed --> [*]

General rules

• A top-up amount must be between 1€ and 1000€ (excluded).
• A user cannot make more than 5 top-ups within a 48-hour period.
• You cannot load an account with a card belonging to that account.

Top-up types

There are 4 possibilities for the top-up:

1. create a top-up without card registration. The card information will have to be filled in again the next time a topup is done.
2. create a top-up with card registration. This first top-up is necessary for one-click top-ups.
3. create a one-click top-up. this is possible only if the card is registred. In this case, the card information was registred during the first top-up, and is not needed during the one-click top-up. Only the 3DS validation remains to be done.
4. creation of a subscription, or recurrent top-up Enabling the card to be saved and not having to validate it on the 3DS the next time it is loaded: it is called "recurrent"

📘

The one-click top-up is customer-initiated.

❗️

Subscription top-up, on the other hand, is reserved exclusively for the partner initiative, for example to take expenses or a subscription.

🚧

It is forbidden to use it on a customer's initiative, in order to dispense with 3DS. For all customer-initiated top-ups, the 3DS is mandatory.

Top-up sequence diagram

sequenceDiagram

Title: general workflow
autoNumber
Actor User
Participant Partner
Participant XPO
Participant Payplug
User ->> Partner : Top-up on my Xpollens account
Partner ->> User : [Screens and workflow until payment form] <br/> import library hosted fields 
Partner ->> User : Display payment form including hosted fields
User ->> Partner : Enter information 
Partner ->> Payplug: Generate token hosted-fields/service/tokenize
Payplug ->> Partner : hfToken 
Activate XPO
Partner ->> XPO : POST /api/v1.1/payins/cardpayments  <br/> {hftoken, appCardId}

alt HTTP/200
XPO ->> Partner : HTTP/200
XPO ->> Partner : callback 1 {status:0}
XPO ->> Payplug : Create authorisation
Payplug ->> XPO: 3DS form
XPO ->> Partner: 3DS form
Partner ->> User: 3DS form
User ->> Payplug: 3DS validated
Payplug ->> XPO: 3DS result
XPO ->> Partner : Validated transaction <br/> Redirect to 'urlReturn'

deactivate XPO 

XPO ->> Partner : callback 1 {status:0}

else HTTP/400: error during Xpollens checks
XPO ->> Partner : HTTP/400
end

Create a top-up

Hosted fields: collection of the card’s confidential data

To create a top-up, you need to implement the Dalenys hosted fields. Please refere to this documentation:

https://developer.dalenys.com/ui/developer-doc/integration-modes/hosted-fields.html

More details about brandselector here: 🔗https://developer.dalenys.com/ui/developer-doc/miscellaneous/brand-selector.html

👍

The accepted card brands are CB, Visa and Mastercard.

🚧

If the card is co-branded, the first choice must be < CB >.

Create an HF token

To proceed, you first need to retrieve a token.

You have two options for obtaining the HFToken.:

• Use the integrated payment HTML page provided by Dalenys.
• Utilize the provided API to generate the token programmatically.

The response payload contains two key pieces of information:

• the HFTOKEN,
• the SELECTEDBRAND,

Both of these values must be included in the input when creating the top-up.

Account Funding Transaction controls (AFT)

As part of a card top-up, it is necessary to declare the identity of the person who owns the card used to fund the account. This information is then checked to:

• ensure the payer is not listed as a fraudulent individual,
• ensure the legitimacy of the funds.

We can distinguish two use cases:

• the holder of the account being topped up and the holder of the card used for the top-up, named MeToMe
• the cardholder is not the account holder, named PersonToPer

Here is the sequence diagram, focused on the main steps

sequenceDiagram

Title: AFT controls
autoNumber
Actor User
Participant Partner
Participant XPO
Participant Payplug
Participant External Bank

User -->> Partner : Collect the payer's data
User -->> Partner : Collect the card's data

Partner ->> Payplug: Generate hfToken
Payplug ->> Partner : hfToken 

Partner ->> XPO : POST /api/v1.1/payins/cardpayments  <br/> {hftoken, payer, ...}
XPO ->> Partner : http 20X

XPO ->> Payplug: process top-up
Payplug ->> Payplug: screening of the payer 
Payplug ->> External Bank: check payer coherency
External Bank ->> Payplug: OK

Payplug ->> XPO : Top-up processed
XPO -->> Partner: callback 1
Partner -->> User: ok

Screening of the payer

Anti-fraud regulations require us to verify that the payer does not appear on any known watchlist. The data used for this screening is taken from the information provided in the top-up creation request.

If no hit is detected, the process continues.
If a hit is detected, the process stops and the payment is canceled.

Payer coherency

The control is performed only if the merchant has an active subscription to the feature.

In this case:

• The issuing bank verifies that the payer is the same person as the cardholder.
• If the verification succeeds, the payment process continues.
• If the verification fails, the payment is rejected.

UI example

Me to Me

• Ask the enduser to the top-up is processed with its personal card
• In this case, you will complete the payer data in the POST request with the data from your database.

Person to Person

• The enduser confirms the card is owned by someone else.
• In this case, display fields needed to collect all data
• Add these data in the POST request

API details

`{
  "payer": {
    "firstName": "string", // string(1-15)     Required
    "lastName": "string", // string(1-15)    Required
    "address": {
      “street“: "110 avenue de France", // Required
      "city": "Paris",   // Required
      "zipCode": "75013",  // Required
      "country": "FR"  // Required
  	},
    "birthDate": "YYYY-MM-DD",// date au format YYYY-MM-DD    , Required
	...
  },

3DS top-up with / without card registration

If the user wants to save the card information, the attribute Card is not null. In this case, for the next top-up:

• the user will not have to fill in the card information
• the user will still need to validate the 3DS

Case 1: without card registration

POST /api/v1.1/payins/cardpayments

• the AppCardId is not filled

{
    "OrderId": "{{orderId_TOPUP_1}}",
    "UrlReturn": "http://rest-integ.s-money.net/HostedFieldsApp/v2/ProcessTopUp",
    "Payer": {
        "Name": "Jean DUPONT",
        "Email": "[email protected]",
        "UserAgent": "Mozilla/5.0 CK={​​}​​ (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
        "UrlReferrer": "https://www.s-money.fr?cart=473",
        "IpAddress": "127.0.0.1"
    },
    "Card": {
		"HFToken":"{{HFToken}}",
		"SelectedBrand":"{{selectedBrand}}"
    },
   "subscriptionTopUp": false,
    "TermsAndConditionsValidationDate": "2022-05-17T17:00:48.0255806+01:00",
    "Payments": [
        {
            "OrderId": "payment_{{orderId_TOPUP_1}}",
            "Amount": 100, //cents
            "Fee": 0, // cents
            "Beneficiary": {
                "AppAccountId": "{{accountId}}"
            }
        }
    ]
}

Case 2: with card registration Same request, with the AppCardId filled.

POST /api/v1.1/payins/cardpayments

{
   [...]
   "Card": {
		"HFToken": "xxx",
		"AppCardId": "CB_Test",
		"SelectedBrand":"{{selectedBrand}}"
    },
   [...]
    }

One-click payment (with 3DS validation)

The card must already be registered.

To create a top up oneclick, you must, in the body of the request, add and fill in the AppCardId parameter instead of the HFToken parameter. This will allow you to directly call the previously registered bank card.

POST /api/v1.1/payins/cardpayments

{
   [...]
   "Card": {
        "AppCardId": "CB_Test",
    },
     "subscriptionTopUp": false
   [...]

    }

With subscription (one-click without 3DS validation)

The card must already be registered.

1st request

• AppCardId and HFToken
• 3DS validation

POST /api/v1.1/payins/cardpayments

{
   [...]
   "card": {
            "HFToken": "xxx"
            "AppCardId": "CB_Test",
    },
     [...]
          "Payments": [
        {
             [...]
            "Beneficiary": {
                "AppAccountId": "{{accountId}}"
            }
	}
]
 [...]
}

Next request

• no HFToken, only the AppCardId
  • no 3DS validation

    • the Payments.Beneficiary.AppAccountId must be the same as then one used for the first request

      POST /api/v1.1/payins/cardpayments

      
      
      
      
      

Top-up life cycle

stateDiagram
state fork_state <<fork>>
state fork_state2 <<fork>>
[*] --> post/v1.1/payins/cardpayments 
post/v1.1/payins/cardpayments   --> fork_state
fork_state --> HTTP/200 : Created
fork_state --> HTTP/400: Not created
HTTP/200 --> fork_state2 : top-up status approved
fork_state2 --> Completed : 3DS completed <br/> Callback 1 status 1
fork_state2 --> Rejected: 3DS failed <br/> Callback 1 status 3
Completed --> [*]
Rejected --> [*]
HTTP/400 --> [*]

ExecCode: Execution Code

The ExecCode translates the status of the CB loading at the PayPlug level and the 3DS validation.

The GET v1.1/users/appUserId/payins/cardpayments/orderId retrieves details.

The execution codes are organized with different ranges:

• 0XXX operation succeeded or still processing
• 4XXX operation rejected because of the bank or the supplier
• 5XXX operation rejected because of a system error
• 6XXX operation rejected because of anti-fraud engine

API, callbacks and technical items

Callbacks

Callback1 : 🔗 Callback1 Callback5 : 🔗Callback5

Create a top-up

🔗TOPUP

• TermsAndConditionsValidationDate: date/time UTC+3
• Date: date/time UTC+2

Erros Code: response 400

Get a Top-Up

By orderid

🔗TopUP by OrderID

• date: date/time UTC+2
• Response code 200

Get All top-up

🔗Get all Top Up

❗️

IMPORTANT

When The GET /api/v1.1/users/USERID/payins/cardpayments API is called without additional parameters (startDate, endDate)it will return the user top-ups starting 30 days before the current date until the current date. The maximum timeframe between startDate and endDate is 31 days

If the timeframe exceeds 31 days then an exception (http/400) will be raised by the API.

{
  "code": 1,
  "errorMessage": "Unknown technical error, please contact Xpollens support. Max date range allowed is 31 days.",
  "title": "Technical error",
  "priority": 2,
  "date": "2024-06-17T15:04:39.3684193Z",
  "operationId": "f7903cd3b34ef856bfdf493d4ad65f9f",
  "httpStatusCode": 400
}

Refund a Top-Up

👍

Top-Up reimbursement may be total or partial.

This reimbursement allows you to return to the original situation in terms of creditlimit, as if the initial operation had not taken place.

Post refund

🔗Refund Top Up

• where orderId = orderId of the original transaction
• and paymentId = paymentId of the original transaction

❗️

If the cancellation is made on the same day, before the merchant discount, then there is only one transaction, with the status Refund.

In the opposite case, two operations will exist: the original operation with Completed status, and the Refund operation with status Completed and Rtransaction = true

Response

Response

Error codes

How to test

Sandbox

1- Get a HF TOKEN

On test environments, you can either use the integrated payment HTML page provided by Dalenys or use the following API to get an HFToken

POST https://secure-test.be2bill.com/hosted-fields/service/tokenizewith the following parameters (x-www-form-urlencoded) :

CARDCODE=4464215790990001
CARDVALIDITYDATE=06/24
CARDCVV=123
SELECTEDBRAND=visa
APIKEYID=<provided on demand>

cUrl example

curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' \ 
-i 'https://secure-test.be2bill.com/hosted-fields/service/tokenize' \ 
--data 'CARDCODE=4464215790990001&CARDVALIDITYDATE=06/24&CARDCVV=123&SELECTEDBRAND=visa&APIKEYID=<PROVIDED ON DEMAND>'

Response code

{
    "EXECCODE": "0000",
    "MESSAGE": "Operation succeeded.",
    "HFTOKEN": "7016e7df-04ef-4c92-83e2-8c5d1155c2b6",
    "CARDTYPE": "VISA",
    "CARDVALIDITYDATE": "06-24",
    "CARDCODE": "446421XXXXXX0001",
    "SELECTEDBRAND": "visa",
    "BINTYPE": "Consumer",
    "BINBRANDS": [
        {
            "BRAND": "VISA",
            "SERVICETYPE": "Debit"
        }
    ],
    "BINNETWORK": "VISA"
}

2- Create a top_up with

POST /v1.1/payins/cardpayments

{
    "OrderId": "{{orderId_TOPUP_1}}",
    "UrlReturn": "http://rest-integ.s-money.net/HostedFieldsApp/v2/ProcessTopUp",
    "Payer": {
        "Name": "Jean DUPONT",
        "Email": "[email protected]",
        "UserAgent": "Mozilla/5.0 CK={​​}​​ (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
        "UrlReferrer": "https://www.s-money.fr?cart=473",
        "IpAddress": "127.0.0.1"
    },
    "subscriptionTopUp": false,
    "Card": {
        "HFToken":"{{HFTOKEN}}",
        "AppCardId": "CB_{{orderId_TOPUP_1}}",
	"SelectedBrand": "VISA"
    },
    "TermsAndConditionsValidationDate": "2022-05-17T17:00:48.0255806+01:00",
    "Payments": [
        {
            "OrderId": "payment_{{orderId_TOPUP_1}}",
            "Amount": 100, //cents
            "Fee": 0, // cents
            "Beneficiary": {
                "AppAccountId": "{{accountId}}"
            }
        }
    ]
}

3- Validate 3DS

1. On postman, click on visualize > Inspect vizualisation > copy link address
2. Paste it in your browser.
3. Validate 3DS.

4- Create a refund

POST /V1.1/users/accountId/payins/cardpayments/orderId_TOPUP_1/payments/payment_orderId_TOPUP_1/refunds

{
        "orderid" : "orderId_refund",
        "amount" : {amount} //cents
}

Production

When the alphatests are launched, the Payplug library and url configurations need to be modified. Ask your Customer Integration Manager.

FAQ

Can I access to the Payplug backoffice?

No, you don't have access. Only xpollens employees have access.

After a top-up, how to redirect my enduser from the 3DS page to the application.

You need to fill the UrlReturn in the post.

Can I customise the 3DS page?

No, you can only modify the logo and the merchant name.

I can't find my top-ups

The GET /api/v1.1/users/userid/payins/cardpayments has some limitations regarding the timeframe and the maximum number of records it can return.

Please see the note here for more detailed information : 🔗 Get All top-ups

Can we have Top-Up without 3DS Yes,

• if the subscription mode is used
• for B2B cards