You are viewing the docs for an old API version (v2) → View v2.01

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
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

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, AMEX, MAESTRO, P24, IDEAL, BCMC

The type of Card

The type of card . The card type is optional, but the default parameter is "CB_VISA_MASTERCARD" .

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": "lorem",
"RegistrationData": "lorem",
"CardType": "CB_VISA_MASTERCARD",
"CardId": "14213157",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Status": "CREATED"
}

Create a Card Registration

POST .../v2/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
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR
required

The currency - should be ISO_4217 format

CardType
CardType

CardType:

CB_VISA_MASTERCARD, DINERS, AMEX, MAESTRO, P24, IDEAL, BCMC

The type of Card
optional

The type of card . The card type is optional, but the default parameter is "CB_VISA_MASTERCARD" .

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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"UserId": "8494514",
"Currency": "EUR",
"CardType": "CB_VISA_MASTERCARD"
}
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"Tag": "",
"UserId": "",
"Currency": "",
"CardType": ""
}

Update a Card Registration

PUT .../v2/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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
PUT .../CardRegistrations/:CardRegistrationId/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"RegistrationData": "lorem"
}
PUT .../CardRegistrations// HTTP/1.1
Body Parameters :
{
"Tag": "",
"RegistrationData": ""
}

View a Card Registration

GET .../v2/ClientId

The ID of your client account

/cardregistrations/CardRegistrationId

The ID of a card registration

/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../cardregistrations/:CardRegistrationId/ HTTP/1.1
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, AMEX, MAESTRO, P24, IDEAL, BCMC

The type of Card

The type of card . The card type is optional, but the default parameter is "CB_VISA_MASTERCARD" .

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.

BankCode
string

string:

Maximum length is 255 characters
Active
bool

bool:

true, false

Whether the card is active or not

Currency
Currency

Currency:

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, JPY, NOK, PLN, SEK, USD, ZAR

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/ClientId

The ID of your client account

/cards/CardId

The ID of a card

/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../cards/:CardId/ HTTP/1.1
GET .../cards// HTTP/1.1

List Cards for a User

GET .../v2/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:

CreationDate:ASC / CreationDate:DESC
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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • 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/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:

CreationDate:ASC / CreationDate:DESC
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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • 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/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:

CreationDate:ASC / CreationDate:DESC
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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../cards/fingerprints/:Fingerprint/users/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821
}
GET .../cards/fingerprints//users/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate":
}

List Transactions for a Card Fingerprint

GET .../v2/ClientId

The ID of your client account

/cards/fingerprints/Fingerprint

A unique representation of a 16-digits card number

/transactions/

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:

CreationDate:ASC / CreationDate:DESC
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

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED
optional

The status of the transaction (you can filter your transactions list by multiple Status values, each one must be separated by a comma)

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT
optional

Filter for a specific value

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT
optional

Filter for a specific value

ResultCode
string

string:

Maximum length is 255 characters
optional

The result code of the transaction (you can filter your transactions list by multiple ResultCode values, each one must be separated by a comma)

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../cards/fingerprints/:Fingerprint/transactions/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"Status": "CREATED,FAILED",
"Nature": "REGULAR,REFUND",
"Type": "PAYIN,PAYOUT",
"ResultCode": "000000,009199"
}
GET .../cards/fingerprints//transactions/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"Status": "",
"Nature": "",
"Type": "",
"ResultCode": ""
}

Deactivate a Card

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

PUT .../v2/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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
PUT .../cards/:CardId/ HTTP/1.1
Body Parameters :
{
"Active": false
}
PUT .../cards// HTTP/1.1
Body Parameters :
{
"Active": ""
}
Share feedback