How to process a card payment

​

Introduction

This how-to guide will take you through the steps to successfully simulate a payment by card in the Sandbox testing environment.

​

1. Create a user

In this guide, we’ll register a natural user to represent a private individual who just needs to make a payment on your platform.

Payers only need to provide a first name, last name, and email (see the user categories for more information).

POST /V2.01/{ClientId}/users/natural

In response, the API returns an Id for the user, which you’ll need for the next step.

{
    "Id": "user_m_01J18HZSACR1EMYNY1TBS8KTJD"
}

​

2. Create a wallet for the user

All users need a wallet to which they can pay funds, even it it is immediately transfered to another wallet (for example, to a marketplace seller).

Use the Id of the user as the owner of the wallet:

POST /V2.01/{ClientId}/wallets

In response, the API returns an Id for the wallet, which you’ll need to request the payment.

{
    "Id": "wlt_m_01J18J1SQGG6KXNM3F8GD674TP"
}

​

3. Create a card registration

The tokenization process enables your platform to handle sensitive card details with Mangopay.

Create a Card Registration object to start this process, using the Id of the user as the UserId.

You also need to define the currency and type of the card at this stage.

POST /v2.01/{ClientId}/cardregistrations

In response, the API returns the card registration object:

{
    "Id": "cardreg_m_01J18JJA7VH1Q38V3Z3F2C059D",
    "Tag": null,
    "CreationDate": 1719348570,
    "UserId": "user_m_01J18HZSACR1EMYNY1TBS8KTJD",
    "AccessKey": "1X0m87dmM2LiwFgxPLBJ",
    "PreregistrationData": "ObMObfSdwRfyE4QClGtUc1GGKTRAkntk_O93wafMNRiNkMGlbaUXBaLbPahxf7VD2ddFLVXdicolcUIkv_kKEA",
    "RegistrationData": null,
    "CardId": null,
    "CardType": "CB_VISA_MASTERCARD",
    "CardRegistrationURL": "https://pci.sandbox.mangopay.com/api/mangopay/vault/tokenize/eyJjbGllbnQiOiJjbGllbnRJZCIsInRva2VuIjoidW5xaXVlVG9rZW4ifQ==",
    "ResultCode": null,
    "ResultMessage": null,
    "Currency": "EUR",
    "Status": "CREATED"
}

From this response, you will need the following values for the next step:

• AccessKey
• PreregistrationData
• CardRegistrationURL

​

4. Send data to the tokenization server

The dedicated tokenization server allows your platform to process sensitive card data without exposing you or your end users to any security risk.

Make a request to the CardRegistrationURL using the previously saved AccessKey and PreregistrationData:

• Use AccessKey data for the accessKeyRef parameter
• Use PreregistrationData data for the data parameter

You also need the end user’s card details entered on the payment page:

The content-type for this call is “application/x-www-form-urlencoded”.

POST {CardRegistrationURL}

In response, the API returns an encoded data string:

data=qc_ShKapgXF-A2t_OC72Ko0o568aiaCttReld3UFN6czA9d3uGhyoKRez0uSm5xbV52qH2pQE2MInBd_End2fZvHB1ZEXCpfiSAoeP1mpcuMSPVhQbki1iMJJFqJ1t8r0ftIYwFxOdfmDQ5GtM_cIg

You’ll need this string for the next step.

​

5. Update the card registration with tokenization data

Update the Card Registration object by sending the data token returned by the tokenization server as the RegistrationData.

You should also provide the cardholder’s name at this stage, which will be added to the Card object.

PUT /v2.01/{ClientId}/cardregistrations/CardRegistrationId

In response, the API returns the Card Registration object.

{
    "Id": "cardreg_m_01J18JJA7VH1Q38V3Z3F2C059D",
    "Tag": null,
    "CreationDate": 1719348570,
    "UserId": "user_m_01J18HZSACR1EMYNY1TBS8KTJD",
    "AccessKey": "1X0m87dmM2LiwFgxPLBJ",
    "PreregistrationData": "ObMObfSdwRfyE4QClGtUc1GGKTRAkntk_O93wafMNRiNkMGlbaUXBaLbPahxf7VD2ddFLVXdicolcUIkv_kKEA",
    "RegistrationData": "data=qc_ShKapgXF-A2t_OC72Ko0o568aiaCttReld3UFN6czA9d3uGhyoKRez0uSm5xbV52qH2pQE2MInBd_End2fZvHB1ZEXCpfiSAoeP1mpcuMSPVhQbki1iMJJFqJ1t8r0ftIYwFxOdfmDQ5GtM_cIg",
    "CardId": "card_m_01J18JJSZTKET9SX9V0W69M8H8",
    "CardType": "CB_VISA_MASTERCARD",
    "CardRegistrationURL": "https://pci.sandbox.mangopay.com/api/mangopay/vault/tokenize/eyJjbGllbnQiOiJjbGllbnRJZCIsInRva2VuIjoidW5xaXVlVG9rZW4ifQ==",
    "ResultCode": "000000",
    "ResultMessage": "Success",
    "Currency": "EUR",
    "Status": "VALIDATED"
}

The CardId is the tokenized version of the card that you can use in the next step to request the payment.

​

6. Get the end user’s session data

In your integration, you’ll also need to capture information from your end user’s browsing session to be able to request the payment.

In Sandbox, you can use dummy data.

​

IP address

You need to send the end user’s IP address in IPV4 or IPV6 format. You can collect this when the user requests the payment, or else use an IP lookup service such as Cloudfare or ipify.

​

Browser information

You also need to collect data about the end user’s browser.

• On a website, this data can be obtained from the browser.
• In a mobile app, you need to open a webview to fetch data from the browser (in the same way as for a website).

let browserInfo = {
  acceptedHeader: navigator.languages,
  javaEnabled: navigator.javaEnabled(),
  language: navigator.language,
  colorDepth: window.screen.colorDepth,
  screenHeight: window.screen.height,
  screenWidth: window.screen.width,
  timeZoneOffset: new Date().getTimezoneOffset(),
  userAgent: navigator.userAgent,
  javascriptEnabled: true
}

console.log(browserInfo);

​

7. Request the payment (Direct Card PayIn)

Now that you have a CardId, you can request the payment to the wallet using the Direct Card PayIn object.

Create the pay-in request using:

• The CardId
• The IP address and browser information
• The Id of the User as the AuthorId
• The Id of the user’s Wallet as the CreditedWalletId

In your integration, when you make the payment request you also need to:

• Be ready to handle 3DS authentication (Step 6)
• Specify the page to which the user will be returned after payment (Step 7)

Read these steps before continuing with the payment request:

POST /v2.01/{ClientId}/payins/card/direct

​

8. Redirect the user to 3DS protocol (if required)

Redirect the user to the SecureModeRedirectURL value to complete strong customer authentication with the 3DS protocol, unless it is null. If SecureModeRedirectURL is null, this means that 3DS is not required and no redirection is needed.

You can also use the SecureModeNeeded boolean to determine this redirection behavior.

In Sandbox, follow the link returned in the SecureModeRedirectURL to access the authentication simulator.

​

9. Return the user after payment

After the payment, whether it includes 3DS or not and whatever the outcome, the end user is returned to the SecureModeReturnURL which you defined.

The Mangopay API returns your SecureModeReturnURL with the Id of the pay-in transaction attached as a query parameter in the following format:

https://www.example.com?transactionId=Id

Mangopay updates the Status of the pay-in to indicate a successful or failed payment depending on the outcome of the end user’s authentication.

You should set up hook notifications for the following event types to be notified of the outcome:

• PAYIN_NORMAL_SUCCEEDED
• PAYIN_NORMAL_FAILED

Once your system receives a webhook, call the GET View a PayIn endpoint (using its Id) to confirm the result of the transaction. This allows you to customize the end user’s experience after the payment.

If the pay-in is successful, the card’s Validity parameter is set to Valid and it can be used for other payments at a later stage.

​

10. Deactivate the card (if required)

Once the pay-in is successful, if the end user did not request to save their card for later, set the card’s Active parameter to false to deactivate the card. This action is irreversible.

PUT /v2.01/{ClientId}/cards/{CardId}

​

Related resources