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 the PreRegistrationData , CardRegistrationURL and AccessKey (4. in the diagram)
  3. The user posts PreRegistrationData, AccessKey and card details through a form to the CardRegistrationURL (5. in the diagram)
  4. Get a RegistrationData back (6. in the diagram)
  5. Edit the CardRegistration Object 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)

You need to do your tests in sandbox mode only with the testing cards

If you don’t want to save the card you must change the field ACTIVE in the card object to false as shown here

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 – (this approach or anything similar) is strictly not allowed

Registration Flow

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.
  • A successful transaction (preauthorization, pay-in, or recurring) within 24 hours after the card registration is required to validate a CardId. Otherwise, the card Validity will be set to “INVALID” and a new card registration will be necessary to make a payment.

Parameters

UserId
string

string:

Maximum length is 255 characters

The object owner's UserId

Currency
CurrencyCard

CurrencyCard:

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

The currency of the card - 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

{
"UserId": "8494514",
"Currency": "lorem",
"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.01/ClientId

The ID of your client account

/cardregistrations

Parameters

UserId
string

string:

Maximum length is 255 characters
required

The object owner's UserId

Currency
CurrencyCard

CurrencyCard:

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

The currency of the card - 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)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"UserId": "8494514",
"Currency": "lorem",
"CardType": "CB_VISA_MASTERCARD"
}
POST .../cardregistrations HTTP/1.1
Body Parameters :
{
"UserId": "",
"Currency": "",
"CardType": ""
}

Post Card info

3. Send card details (Payment form)

You have to send the fields AccessKey, PreregistrationData and the user card details (card number, expiry date and CSC) to the tokenization server through a form posted on the CardRegistrationURL. We recommend using the following registration kits to remain compliant and avoid any risks associated to sensitive card data :

N.B : Users’ card information is directly sent to our PCI-DSS compliant PSP without reaching our servers. That is why the POST URL in this endpoint differs from the other endpoints. The retrieved data from this POST cannot be used or exploited without an authenticated MANGOPAY API call.

Please note that the expiry date posted to the CardRegistrationURL must be in this format: MMYY / Please note that parameters in this POST should be send in "x-www-form-urlencoded" instead of the classic JSON format.

You can get the CardRegistrationURL from the "Create a card registration" json response.

POST : https://homologation-webpayment.payline.com/webpayment/getToken

Parameters

accessKeyRef
string

string:

Maximum length is 255 characters

AccessKey value, retrieved from the previous "Create Card registration" JSON response

data
string

string:

Maximum length is 255 characters

PreregistrationData value, retrieved from the previous "Create Card registration" JSON response

cardNumber
string

string:

Maximum length is 255 characters

Card details number. More info in Testing payment section.

cardExpirationDate
string

string:

Maximum length is 255 characters

Card expiration date. For all cards, the expiry date can be any month/year in the future

cardCvx
string

string:

Maximum length is 255 characters

CSV (the three numbers on the back of the card)

IMPORTANT: card details must never pass via your server – you must use the card registration process and not implement a different system where the card details may touch your server – (this approach or anything similar) is strictly not allowed.

4. Get the RegistrationData key (After registration)

After posting card details, you get a RegistrationData. Here is an example : data=gcpSOxwNHZutpFWmFCAYQu1kk25qPfJFdPaHT9kM3gKumDF3GeqSw8f-k8nh-s5OC3GNnhGoF

Update a Card Registration

5. Edit with RegistrationData (An input JSON example)

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

{
"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.

PUT .../v2.01/ClientId

The ID of your client account

/CardRegistrations/CardRegistrationId

The ID of a card registration

/

Parameters

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 :
{
"RegistrationData": "lorem"
}
PUT .../CardRegistrations// HTTP/1.1
Body Parameters :
{
"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
GET .../cardregistrations// HTTP/1.1

The Card object

The Card object lets you get the card details.

Parameters

ExpirationDate
string

string:

Maximum length is 255 characters

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
CurrencyCard

CurrencyCard:

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

The currency of the card - 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

{
"ExpirationDate": "1019",
"Alias": "497010XXXXXX4414",
"CardProvider": "Mangopay Ltd",
"CardType": "CB_VISA_MASTERCARD",
"Country": "FR",
"Product": "G",
"BankCode": "00152",
"Active": true,
"Currency": "lorem",
"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
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/
  • 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 .../users//cards/ HTTP/1.1

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
  • 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 .../cards/fingerprints/ HTTP/1.1

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/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../cards/fingerprints/:Fingerprint/users/ HTTP/1.1
GET .../cards/fingerprints//users/ HTTP/1.1

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
}
PUT .../cards// HTTP/1.1
Body Parameters :
{
"Active": ""
}

List Transactions 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

/transactions/
  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../cards/fingerprints/:Fingerprint/transactions/ HTTP/1.1
GET .../cards/fingerprints//transactions/ HTTP/1.1
Share feedback