The Card Registration Object

You need to register a card in order to process a Direct PayIn. Card registration enables you to tokenize a Card. These are the steps to follow:

  1. Create a CardRegistration Object (1. 2. & 3. in the diagram)
  2. Get a PreRegistrationData key (4. in the diagram)
  3. The user posts PreRegistrationData, AccessKey and card details through a form (PHP & JS samples) to the CardRegistrationURL (5. in the diagram)
  4. Get a RegistrationData back (6. in the diagram)
  5. Edit the CardRegistration Object (POST method) with the RegistrationData just received (7.8. in the diagram)
  6. Get the CardId ready to use into the Direct PayIn Object (9. in the diagram)
  • If you don’t want to save the card you must change the field ACTIVE in the card object to false as shown here
  • You need to do your tests in sandbox mode only with the testing cards
  • From 24/02/2015, some out-dated browsers will not support payin webs nor card registrations – more info

IMPORTANT: card details must never pass via your server – therefore you must use the card registration process given below and not implement a different system where the card details may touch your server and then you use cURL etc to create the card – (this approach or anything similar) is strictly not allowed

Registration Flow

The card registration method lets you customise your payment page. This page can be hosted on your own.

Here is the registration flow (the last step correponds to the Direct PayIn): alt

  • It is imperative to inform your users if you are registering their cards
  • The validity of a registered card (CardId) before a payment or a pre-authorisation is 30min maximum. Once one of these operations is made, the card Validity field change to "VALID". Then, it is available up to the expiry date

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

UserId
string

string:

Maximum length is 255 characters

The object owner's UserId

Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

AccessKey
string

string:

Maximum length is 255 characters

A special key to use when registering a card

PreregistrationData
string

string:

Maximum length is 255 characters

A specific value to pass to the CardRegistrationURL

CardRegistrationURL
string

string:

Maximum length is 255 characters

The URL to submit the card details form to

RegistrationData
string

string:

Maximum length is 255 characters

Having registered a card, this confirmation hash needs to be updated to the card item

CardType
CardType

CardType:

CB_VISA_MASTERCARD, DINERS, MASTERPASS, MAESTRO, P24, IDEAL, BCMC, PAYLIB

The type of Card

The type of card

CardId
string

string:

Maximum length is 255 characters

The ID of a card

ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

Status
CardStatus

CardStatus:

CREATED, VALIDATED, ERROR

Status of the card registration

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"UserId": "8494514",
"Currency": "EUR",
"AccessKey": "jsy76Nskz",
"PreregistrationData": "qKEKexdo_NolxfBziaxZIihJXwegzdpOozxsdAPI4lewHtXrlsvWAp853ww9S4wCy-yiraxeE",
"CardRegistrationURL": "blabla",
"RegistrationData": "blabla",
"CardType": "CB_VISA_MASTERCARD",
"CardId": "14213157",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Status": "CREATED"
}

Create a Card Registration

POST .../v2.01/ClientId

The ID of your client account

/cardregistrations

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

UserId
string

string:

Maximum length is 255 characters

required

The object owner's UserId

Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

required

The currency - should be ISO_4217 format

CardType
CardType

CardType:

CB_VISA_MASTERCARD, DINERS, MASTERPASS, MAESTRO, P24, IDEAL, BCMC, PAYLIB

The type of Card

optional

The type of card

Steps

1. Send the request (An input JSON example)

2. Get the reply (An output JSON example)

3. Send card details (Payment form)

Now you have to send to the tokenization server the fields AccessKey, PreregistrationData and the user card details (card number, expiry date and CSC) through a form posted at the CardRegistrationURL. Here are 2 PHP samples to post card details:

PHP integration sample: https://github.com/MangoPay/mangopay2-php-sdk/tree/master/demos/paymentDirect JS integration sample: https://github.com/MangoPay/mangopay2-php-sdk/tree/master/demos/paymentDirect/js

Please note that the expiry date posted to the CardRegistrationURL must be in this format: MMYY

4. Get the RegistrationData key (After registration) After posting card details, you get a RegistrationData. Here is an example :

data=gcpSOxwNHZutpFWmFCAYQu1kk25qPfJFdPaHT9kM3gKumDF3GeqSw8f-k8nh-s5OC3GNnhGoFONuAyg1RZQW6rVXooQ_ysKsz09HxQFEJfb-6H4zbY2Nnp1TliwkEFi4 

You also have to put "data=" into the field too

Now, you have to edit the CardRegistration Object (PUT method) with this RegistrationData just received

5. Edit with RegistrationData (An input JSON example)

{
"RegistrationData" : "data=gcpSOxwNHZutpFWmFCAYQu1kk25qPfJFdPaHT9kM3gKumDF3GeqSw8f-k8nh-s5OC3GNnhGoFONuAyg1RZQW6rVXooQ_ysKsz09HxQFEJfb-6H4zbY2Nnp1TliwkEFi4"
}

Finally, the card is created. You are now able to get the card details with the Card Object, and pay using the Card Direct PayIn Object.

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"UserId": "8494514",
"Currency": "EUR",
"CardType": "CB_VISA_MASTERCARD"
}
require_once("mangopay.php");

try {


$CardRegistration = new \MangoPay\CardRegistration();
$CardRegistration->Tag = "custom meta";
$CardRegistration->UserId = "8494514";
$CardRegistration->Currency = "EUR";
$CardRegistration->CardType = "CB_VISA_MASTERCARD";

$Result = $Api->CardRegistrations->Create($CardRegistration);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"Tag": "",
"UserId": "",
"Currency": "",
"CardType": ""
}

Update a Card Registration

PUT .../v2.01/ClientId

The ID of your client account

/CardRegistrations/CardRegistrationId

The ID of a card registration

/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

RegistrationData
string

string:

Maximum length is 255 characters

optional

Having registered a card, this confirmation hash needs to be updated to the card item

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../CardRegistrations/:CardRegistrationId/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"RegistrationData": "blabla"
}
require_once("mangopay.php");

try {

$CardRegistration = new \MangoPay\CardRegistration();
$CardRegistration->Tag = "custom meta";
$CardRegistration->Id = 12638997;
$CardRegistration->RegistrationData = "blabla";

$Result = $Api->CardRegistrations->Update($CardRegistration);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../CardRegistrations// HTTP/1.1
Body Parameters :
{
"Tag": "",
"RegistrationData": ""
}

View a Card Registration

GET .../v2.01/ClientId

The ID of your client account

/cardregistrations/CardRegistrationId

The ID of a card registration

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../cardregistrations/:CardRegistrationId/ HTTP/1.1
require_once("mangopay.php");

try {

$CardRegistrationId = 12638997;

$CardRegistration = $Api->CardRegistrations->Get($CardRegistrationId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../cardregistrations// HTTP/1.1

The Card Object

The Card object lets you get the card details.

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

ExpirationDate
timestamp

timestamp

The expiry date of the card - must be in format MMYY

Alias
string

string:

Maximum length is 255 characters

A partially obfuscated version of the credit card number

CardProvider
string

string:

Maximum length is 255 characters

The provider of the card

CardType
CardType

CardType:

CB_VISA_MASTERCARD, DINERS, MASTERPASS, MAESTRO, P24, IDEAL, BCMC, PAYLIB

The type of Card

The type of card

Country
string

string:

Maximum length is 255 characters

The Country of the Address

Product
string

string:

Maximum length is 255 characters

The card product type - more info

BankCode
string

string:

Maximum length is 255 characters

Active
bool

bool:

true, false

Whether the card is active or not

Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

Validity
CardValidity

CardValidity:

UNKNOWN, VALID, INVALID

The validity of the Card

Whether the card is valid or not. Once they process (or attempt to process) a payment with the card we are able to indicate if it is "valid" or "invalid". If they didn’t process a payment yet the "Validity" stay at "unknown".

Fingerprint
string

string:

Maximum length is 255 characters

A unique representation of a 16-digits card number

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"ExpirationDate": 1019,
"Alias": "497010XXXXXX4414",
"CardProvider": "Mangopay Ltd",
"CardType": "CB_VISA_MASTERCARD",
"Country": "FR",
"Product": "G",
"BankCode": "00152",
"Active": true,
"Currency": "EUR",
"Validity": "VALID",
"Fingerprint": "50a6a8da09654c4cab901814a741f924"
}

View a Card

GET .../v2.01/ClientId

The ID of your client account

/cards/CardId

The ID of a card

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../cards/:CardId/ HTTP/1.1
require_once("mangopay.php");

try {

$CardId = 14213157;

$Card = $Api->Cards->Get($CardId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../cards// HTTP/1.1

List Cards for a User

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/cards/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/cards/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC"
}
GET .../users//cards/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": ""
}

List Cards for a Fingerprint

GET .../v2.01/ClientId

The ID of your client account

/cards/fingerprints/Fingerprint

A unique representation of a 16-digits card number

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../cards/fingerprints/:Fingerprint HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC"
}
GET .../cards/fingerprints/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": ""
}

List Users for a Card Fingerprint

GET .../v2.01/ClientId

The ID of your client account

/cards/fingerprints/Fingerprint

A unique representation of a 16-digits card number

/users/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../cards/fingerprints/:Fingerprint/users/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821
}
require_once("mangopay.php");

try {

$Page = 1;
$Per_Page = 25;
$Sort = "CreationDate:DESC";
$BeforeDate = 1463440221;
$AfterDate = 1431817821;
$Fingerprint = "50a6a8da09654c4cab901814a741f924";

$ = $Api->->($Page, $Per_Page, $Sort, $BeforeDate, $AfterDate, $Fingerprint);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../cards/fingerprints//users/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate":
}

Deactivate a Card

Note that once deactivated, a card can't be reactivated afterwards

PUT .../v2.01/ClientId

The ID of your client account

/cards/CardId

The ID of a card

/

Parameters

Active
bool

bool:

true, false

optional

Whether the card is active or not

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../cards/:CardId/ HTTP/1.1
Body Parameters :
{
"Active": false
}
require_once("mangopay.php");

try {

$Card = new \MangoPay\Card();
$Card->Id = 14213281;
$Card->Active = false;

$Result = $Api->Cards->Update($Card);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../cards// HTTP/1.1
Body Parameters :
{
"Active": ""
}