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.

Prerequisites

A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard

Note – Postman collection contains this flow

The public Mangopay API Postman collection contains a dedicated folder with the endpoints for this how-to guide.

Get started →

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.

Best practice - Use Mangopay’s card SDKs

Mangopay’s Checkout SDK and Vault SDK take care of the tokenization steps (Steps 2 & 3) for you, and generate a CardId.

Simplify your integration on web, iOS, and Android.

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:

Property	Type	Description
`cardNumber`	string	The card number to be tokenized, without any separators.
`cardExpirationDate`	string (Format: “MMYY”)	The expiration date of the card.
`cardCvx`	string	The card verification code (on the back of the card, usually 3 digits).

Warning - Card details must never pass via your server

For security reasons, it is strictly forbidden to send the card details to your own server. You must rely on the dedicated PCI-DSS compliant tokenization server as described below.

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).

Browser information - JavaScript example
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);

API child parameter	Type	Description	JavaScript example
`AcceptHeader`	string	The exact content of the HTTP accept headers as sent to the platform from the end user’s browser.	None, collected server-side
`JavaEnabled`	boolean	Whether or not the end user’s browser has the ability to execute Java.	`navigator.javaEnabled()`
`Language`	string (Max. length: 6 characters)	The browser language, made up of the language code and the country (e.g., “en-US”).	`navigator.language` or `navigator.userLanguage`
`ColorDepth`	integer (Allowed values: 1, 4, 8, 15, 16, 24, 30, 32, 48)	The value representing the depth of the screen’s color palette for displaying images, in bits per pixel.	`window.screen.colorDepth`
`ScreenHeight`	integer (Max. length: 6 characters)	The height of the screen in pixels.	`window.screen.height`
`ScreenWidth`	integer (Max. length: 6 characters)	The width of the screen in pixels.	`window.screen.width`
`TimeZoneOffset`	integer	The difference in minutes between the browser’s timezone and UTC.	`new Date().getTimezoneOffset()`
`UserAgent`	string (Max. length: 255 characters)	The exact content of the HTTP User-Agent header. Max. length: 255 characters.	`navigator.userAgent`
`JavascriptEnabled`	boolean	Whether or not the end user’s browser has the ability to execute JavaScript.	`true`

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.

Note - Recurring card payments and preauthorizations require other endpoints

The Direct Card PayIn object represents a one-time payment with a registered card.

For subscriptions and other recurring card payments, use the Recurring PayIn Registration object.

To reserve funds on a card for capture later, use the Preauthorization and Deposit Preauthorization objects.

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)

Warning - End user’s approval needed to save card details

Under no circumstances should card information be kept without the end user’s approval.

If you don’t have the end user’s approval, you need to deactivate the card systematically after use in your implementation.

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.

Note - The card can be registered multiple times

Deactivating the card will not prevent the end user from making a payment with the same card in future. You will need to go through the card registration process again.

Introduction

Users

User verification

Payments

Payouts

FX services

Fraud prevention

How to process a card payment

Introduction

1. Create a user

2. Create a wallet for the user

3. Create a card registration

4. Send data to the tokenization server

5. Update the card registration with tokenization data

6. Get the end user’s session data

IP address

Browser information

7. Request the payment (Direct Card PayIn)

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

9. Return the user after payment

10. Deactivate the card (if required)

Guide

Guide

Guide

Introduction

Users

User verification

Payments

Payouts

FX services

Fraud prevention

​Introduction

​1. Create a user

​2. Create a wallet for the user

​3. Create a card registration

​4. Send data to the tokenization server

​5. Update the card registration with tokenization data

​6. Get the end user’s session data

​IP address

​Browser information

​7. Request the payment (Direct Card PayIn)

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

​9. Return the user after payment

​10. Deactivate the card (if required)

​Related resources

Guide

Guide

Guide

Introduction

1. Create a user

2. Create a wallet for the user

3. Create a card registration

4. Send data to the tokenization server

5. Update the card registration with tokenization data

6. Get the end user’s session data

IP address

Browser information

7. Request the payment (Direct Card PayIn)

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

9. Return the user after payment

10. Deactivate the card (if required)

Related resources