The PayIn object

The table below describes the different PayIn methods available with the MANGOPAY API, and which capabilities are available for each. Note that for certain card payments, there may be an extra step for 3D-Secure to be completed - you can read more about the triggers for this step here.

The appropriate test cards/data can be found here.

PayIn Web PayIn Direct 3DSecure Refund Currency Payment Type
CB/Visa/Mastercard alt Yes Yes Yes Yes EUR, GBP, USD, CHF, PLN, NOK, SEK, DKK, CAD, AUD Card
Maestro alt Yes Yes Always 3DS Yes EUR Card
AMEX (Public Beta, contact support) Yes Yes Always 3DS Yes EUR, GBP, USD, CHF, PLN, NOK, SEK, DKK, CAD, AUD Card
Diners alt Yes Yes No Yes EUR Card
Przelewy24 alt Yes No No Yes PLN Card
iDeal alt Yes No No Yes EUR Card
Bancontact/Mister Cash alt Yes Yes Always 3DS Yes EUR Card
PayLib alt Yes No No Yes EUR Card
Sofort alt Yes No No Yes EUR Direct Debit
Giropay alt Yes No No Yes EUR Direct Debit
Direct Debit alt No Yes No Yes EUR/GBP Direct Debit
Bankwire alt No Yes No No All Bankwire

If you need more currency, please contact us

Parameters

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of payin

ExecutionType
PayInExecutionType

PayInExecutionType:

WEB, DIRECT, EXTERNAL_INSTRUCTION

The execution type of the payin

The type of execution for the payin

{
"PaymentType": "CARD",
"ExecutionType": "DIRECT"
}

The Card Web PayIn object

A Pay-in by card and via web interface is a request to process a payment to a wallet for a dedicated user.

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

There is a KYC limit on Pay-Ins in order to fight fraud, money laundering and financing of terrorism. You have to send some documents through the API. Please check the rules to go over the limits

Parameters

ReturnURL
string

string:

Maximum length is 255 characters

The URL to redirect to after payment (whether successful or not)

CardType
CardType

CardType:

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

The type of Card

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

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

Billing
Billing

Billing:

View Sub-parameters

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters

The name of the user

Billing.LastName
string

string:

Maximum length is 255 characters

The last name of the user

Billing.Address
Address

Address:

View Sub-parameters

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage

The language to use for the payment page - needs to be the ISO code of the language

Shipping
Shipping

Shipping:

View Sub-parameters

Contains every useful information's related to the user shipping

Shipping.FirstName
string

string:

Maximum length is 100 characters

The name of the user

Shipping.LastName
string

string:

Maximum length is 100 characters

The last name of the user

Shipping.Address
Address

Address:

View Sub-parameters

The address

Shipping.Address.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

Shipping.Address.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

Shipping.Address.City
string

string:

Maximum length is 255 characters

The city of the address

Shipping.Address.Region
string

string:

Maximum length is 255 characters

The region of the address - this is optional except if the Country is US, CA or MX

Shipping.Address.PostalCode
string

string:

Maximum length is 50 characters

The postal code of the address - can be alphanumeric, dashes or spaces

Shipping.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

TemplateURL
string

string:

Maximum length is 255 characters

The URL to use for the payment page template

StatementDescriptor
string

string:

up to 10 characters

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

RedirectURL
string

string:

Maximum length is 255 characters

The URL to redirect to user to for them to proceed with the payment

{
"ReturnURL": "http://www.my-site.com/returnURL/",
"CardType": "CB_VISA_MASTERCARD",
"SecureMode": "DEFAULT",
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Culture": "EN",
"Shipping": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"TemplateURL": "http://www.my-site.com/templateURL/",
"StatementDescriptor": "Mar2016",
"RedirectURL": "http://www.a-url.com/redirect"
}

Create a Card Web PayIn

Note that you can fully customise the design of your payment page - more info here.

After submission, the object will be waiting to be “SUCCEEDED”. If you wish to be notified in case of a change of status, you can setup hook notifications

POST .../v2.01/ClientId

The ID of your client account

/payins/card/web/

Parameters

Tag
string

string:

Maximum length is 255 characters
optional

Custom data that you can add to this item

AuthorId
string

string:

Maximum length is 255 characters
required

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

DebitedFunds
Money

Money:

View Sub-parameters
required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
required

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

ReturnURL
string

string:

Maximum length is 255 characters
required

The URL to redirect to after payment (whether successful or not)

CardType
CardType

CardType:

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

The type of Card
required

The type of card is required for web payins

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE
optional

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage
required

The language to use for the payment page - needs to be the ISO code of the language

TemplateURLOptions
TemplateURLOptions

TemplateURLOptions:

An array of the PSP and the corresponding template URL

View Sub-parameters
optional

A URL to an SSL page to allow you to customise the payment page. Must be in the format: array("PAYLINE"=>"https://...") and meet all the specifications listed here. Note that only a template for Payline is currently available

TemplateURLOptions.PaylineV2
string

string:

Maximum length is 255 characters
optional

The corresponding template URL V2 with the Payline Javascript Widget

StatementDescriptor
string

string:

up to 10 characters
optional

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

Billing
Billing

Billing:

View Sub-parameters
optional

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters
required

The name of the user

Billing.LastName
string

string:

Maximum length is 255 characters
required

The last name of the user

Billing.Address
Address

Address:

View Sub-parameters
required

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

Shipping
Shipping

Shipping:

View Sub-parameters
optional

Contains every useful information's related to the user shipping

Shipping.FirstName
string

string:

Maximum length is 100 characters
required

The name of the user

Shipping.LastName
string

string:

Maximum length is 100 characters
required

The last name of the user

Shipping.Address
Address

Address:

View Sub-parameters
required

The address

Shipping.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Shipping.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Shipping.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Shipping.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Shipping.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Shipping.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/card/web/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"ReturnURL": "http://www.my-site.com/returnURL/",
"CardType": "CB_VISA_MASTERCARD",
"CreditedWalletId": "8494559",
"SecureMode": "DEFAULT",
"Culture": "EN",
"TemplateURLOptions": {
"PaylineV2": "https://www.mysite.com/template/"
},
"StatementDescriptor": "Mar2016",
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
}
}
POST .../payins/card/web/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"AuthorId": "",
"CreditedUserId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"ReturnURL": "",
"CardType": "",
"CreditedWalletId": "",
"SecureMode": "",
"Culture": "",
"TemplateURLOptions": {
"PaylineV2": ""
},
"StatementDescriptor": "",
"Billing": {
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
}
},
"Shipping": {
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
}
}
}

The Card Direct PayIn object

The Card Direct PayIn Object lets you pay with a registered Card (token). Here are the steps to follow:

  1. Complete the CardRegistration steps (From 1. to 9. in the diagram here)
  2. Create a Direct PayIn object with the CardId received through the CardRegistration (10. in the diagram here)
  3. You need to do your tests in sandbox mode only with the testing cards

There is a KYC limit on Pay-Ins in order to fight fraud, money laundering and financing of terrorism. You have to send some documents through the API. Please check the rules to go over the limits

Remember that you must include the "Powered by MANGOPAY" banner on your payment page - you can download it here

Payment Flow

Here is the CardRegistration flow (tokenization) then the Direct PayIn: alt

It is imperative to inform your users if you are registering their cards.

You can find more information about the difference between Payin through WEB interface and Direct payin here

You can check here the Fees rules

Parameters

SecureModeReturnURL
string

string:

Maximum length is 255 characters

This is the URL where users are automatically redirected after 3D secure validation (if activated)

CardId
string

string:

Maximum length is 255 characters

The ID of a card

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

StatementDescriptor
string

string:

Maximum length is 255 characters

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

Billing
Billing

Billing:

View Sub-parameters

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters

The name of the user

Billing.LastName
string

string:

Maximum length is 255 characters

The last name of the user

Billing.Address
Address

Address:

View Sub-parameters

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

SecurityInfo
SecurityInfo

SecurityInfo:

View Sub-parameters

Contains useful informations related to security and fraud

SecurityInfo.AVSResult
AVSResult

AVSResult:

NO_CHECK,NO_MATCH,ADDRESS_MATCH_ONLY,POSTAL_CODE_MATCH_ONLY,FULL_MATCH

Result of Address Verification System check (only available for UK, US and Australia)

SecureModeNeeded
bool

bool:

true, false

The value is 'true' if the SecureMode was used

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage

The language to use for the payment page - needs to be the ISO code of the language

SecureModeRedirectUrl
string

string:

Maximum length is 255 characters

This is the URL where to redirect users to proceed to 3D secure validation

IpAddress
string

string:

Maximum length is 255 characters

IP Address of the end user (format IPV4 or IPV6)

BrowserInfo
BrowserInfo

BrowserInfo:

This object describes the Browser being user by an end user

View Sub-parameters

This object describes the Browser being user by an end user

BrowserInfo.AcceptHeader
string

string:

Maximum length is 255 characters

Exact content of the HTTP accept headers as sent to the merchant from the shopper’s browser

BrowserInfo.JavaEnabled
bool

bool:

true, false

Whether the user browser has Java enabled

BrowserInfo.Language
string

string:

Maximum length is 255 characters

Language of the browser of the user

BrowserInfo.ColorDepth
int

int

Value representing the bit depth of the colour palette for displaying images, in bits per pixel

BrowserInfo.ScreenHeight
int

int

The height of the screen in pixels

BrowserInfo.ScreenWidth
int

int

The width of the screen in pixels

BrowserInfo.TimeZoneOffset
string

string:

Maximum length is 12 characters

UTC time offset in minutes

BrowserInfo.UserAgent
string

string:

Maximum length is 255 characters

Exact content of the HTTP user-agent header

BrowserInfo.JavascriptEnabled
bool

bool:

true, false

Whether the browser is Javascript enabled

Shipping
Shipping

Shipping:

View Sub-parameters

Contains every useful information's related to the user shipping

Shipping.FirstName
string

string:

Maximum length is 100 characters

The name of the user

Shipping.LastName
string

string:

Maximum length is 100 characters

The last name of the user

Shipping.Address
Address

Address:

View Sub-parameters

The address

Shipping.Address.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

Shipping.Address.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

Shipping.Address.City
string

string:

Maximum length is 255 characters

The city of the address

Shipping.Address.Region
string

string:

Maximum length is 255 characters

The region of the address - this is optional except if the Country is US, CA or MX

Shipping.Address.PostalCode
string

string:

Maximum length is 50 characters

The postal code of the address - can be alphanumeric, dashes or spaces

Shipping.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

{
"SecureModeReturnURL": "http://www.my-site.com/returnURL",
"CardId": "14213157",
"SecureMode": "DEFAULT",
"StatementDescriptor": "Mar2016",
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"SecurityInfo": {
"AVSResult": "NO_CHECK"
},
"SecureModeNeeded": false,
"Culture": "EN",
"SecureModeRedirectUrl": "http://www.a-url.com/3DS-redirect",
"IpAddress": "2001:0620:0000:0000:0211:24FF:FE80:C12C",
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": "+60",
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"Shipping": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
}
}

Create a Card Direct PayIn

POST .../v2.01/ClientId

The ID of your client account

/payins/card/direct/

Parameters

AuthorId
string

string:

Maximum length is 255 characters
required

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

DebitedFunds
Money

Money:

View Sub-parameters
required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
required

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

SecureModeReturnURL
string

string:

Maximum length is 255 characters
required

This is the URL where users are automatically redirected after 3D secure validation (if activated)

CardId
string

string:

Maximum length is 255 characters
required

The ID of a card

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE
optional

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

StatementDescriptor
string

string:

Maximum length is 255 characters
optional

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

Billing
Billing

Billing:

View Sub-parameters
optional

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters
required

The name of the user

Billing.LastName
string

string:

Maximum length is 255 characters
required

The last name of the user

Billing.Address
Address

Address:

View Sub-parameters
required

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage
optional

The language to use for the payment page - needs to be the ISO code of the language

Tag
string

string:

base64 encoded file
optional

Custom data that you can add to this item

IpAddress
string

string:

Maximum length is 255 characters
required

IP Address of the end user (format IPV4 or IPV6)

BrowserInfo
BrowserInfo

BrowserInfo:

This object describes the Browser being user by an end user

View Sub-parameters
required

This object describes the Browser being user by an end user

BrowserInfo.AcceptHeader
string

string:

Maximum length is 255 characters
required

Exact content of the HTTP accept headers as sent to the merchant from the shopper’s browser

BrowserInfo.JavaEnabled
bool

bool:

true, false
required

Whether the user browser has Java enabled

BrowserInfo.Language
string

string:

Maximum length is 255 characters
required

Language of the browser of the user

BrowserInfo.ColorDepth
int

int
required

Value representing the bit depth of the colour palette for displaying images, in bits per pixel

BrowserInfo.ScreenHeight
int

int
required

The height of the screen in pixels

BrowserInfo.ScreenWidth
int

int
required

The width of the screen in pixels

BrowserInfo.TimeZoneOffset
string

string:

Maximum length is 12 characters
required

UTC time offset in minutes

BrowserInfo.UserAgent
string

string:

Maximum length is 255 characters
required

Exact content of the HTTP user-agent header

BrowserInfo.JavascriptEnabled
bool

bool:

true, false
required

Whether the browser is Javascript enabled

Shipping
Shipping

Shipping:

View Sub-parameters
optional

Contains every useful information's related to the user shipping

Shipping.FirstName
string

string:

Maximum length is 100 characters
required

The name of the user

Shipping.LastName
string

string:

Maximum length is 100 characters
required

The last name of the user

Shipping.Address
Address

Address:

View Sub-parameters
required

The address

Shipping.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Shipping.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Shipping.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Shipping.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Shipping.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Shipping.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/card/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"CreditedWalletId": "8494559",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"SecureModeReturnURL": "http://www.my-site.com/returnURL",
"CardId": "14213157",
"SecureMode": "DEFAULT",
"StatementDescriptor": "Mar2016",
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Culture": "EN",
"Tag": "Custom description for this specific PayIn",
"IpAddress": "2001:0620:0000:0000:0211:24FF:FE80:C12C",
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": "+60",
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"Shipping": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
}
}
POST .../payins/card/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"SecureModeReturnURL": "",
"CardId": "",
"SecureMode": "",
"StatementDescriptor": "",
"Billing": {
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
}
},
"Culture": "",
"Tag": "",
"IpAddress": "",
"BrowserInfo": {
"AcceptHeader": "",
"JavaEnabled": "",
"Language": "",
"ColorDepth": ,
"ScreenHeight": ,
"ScreenWidth": ,
"TimeZoneOffset": "",
"UserAgent": "",
"JavascriptEnabled": ""
},
"Shipping": {
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
}
}
}

The Card PreAuthorized PayIn object

Pre-authorized a card before the Pay-In ensures the solvency of a registered card for 7 days.

The overall process is as follows:

  • Register a card (CardRegistration)
  • Create a PreAuthorization with the CardId. This allow you to charge an amount on a card.
  • Charge the card through the PreAuthorized PayIn object (Payins/preauthorized/direct).

How PreAuthorization + validation (Pay-In) works?

  • Once the PreAuthorization object gets Status = "SUCCEEDED" and PaymentStatus = "WAITING" you can charge the card through a PreAuthorized PayIn.
  • The PayIn amount has to be less than or equal to the amount authorized.
  • If a PreAuthorized PayIn fails, you can re-use the same Preauthorization to create a new PayIn while the PreAuthorization has not expired.

Remember that you must include the "Powered by MANGOPAY" banner on your payment page - you can download it here

Note that for Maestro card, you must capture the full amount of the PreAuthorization. You can't capture less.

In Italy, Greece and Spain, the PreAuthorization process is a little particular whereby the pre-authorized amount is actually debited from the bank account (the pre-authorized funds are stored by the bank). The user will get his/her funds back within 7 days.

This case appears on several Banks (we don’t have exhaustive list) in Spain, Italy and Greece. Mangopay recommends you to inform your users or only create €1.00 pre-authorizations in these countries.

Note that some banks do not have the same limits for preauths as normal payins - some users may even need to contact their bank prior to preauthorising very large amounts

Parameters

PreauthorizationId
string

string:

Maximum length is 255 characters

The ID of the Preauthorization object

{
"PreauthorizationId": "12639123"
}

Create a Card PreAuthorized PayIn

An Idempotency Key must be used for multiple Card PreAuthorized PayIns against a single PreAuthorization. This multi-capture feature must be activated by our Support team. Unless accompanied by an Idempotency Key, two pay-ins are considered as duplicate when they meet the following criteria:

  • Made within 24 hours
  • Same amount and currency
  • Same CardId
  • Same OrderRef

Please refer to the following page for more information: https://docs.mangopay.com/guide/idempotency-support

MultiCapture will be enabled by default for all new clients that have been onboarded on MANGOPAY after Amaryllis release (live since 27/01/2020). If it's not your case, please contact us to activate multi-capture. This new feature will be fully rolled out to all clients on 25 June 2021.

POST .../v2.01/ClientId

The ID of your client account

/payins/preauthorized/direct/

Parameters

AuthorId
string

string:

Maximum length is 255 characters
optional

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

DebitedFunds
Money

Money:

View Sub-parameters
required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
required

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

PreauthorizationId
string

string:

Maximum length is 255 characters
required

The ID of the Preauthorization object

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/preauthorized/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"CreditedWalletId": "8494559",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"PreauthorizationId": "12639123"
}
POST .../payins/preauthorized/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"PreauthorizationId": ""
}

The Bankwire Direct PayIn object

A bank wire PayIn is a request to process a payment by bank wire. The workflow is the following:

  • Call the /payins/bankwire/direct object. You’ll receive MANGOPAY bank account details and a reference.
  • Display this information to your user
  • The user has to proceed a Bank wire to the display bank account with the reference
  • Once MANGOPAY receive the payment the e-money is created and the targeted e-wallet is credited.

The bank wire payin will expire after one month if the payment has not been received by MANGOPAY within this time.

There is a KYC limit on Pay-Ins in order to fight fraud, money laundering and financing of terrorism. You have to send some documents through the API. Please check the rules to go over the limits

Parameters

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of payin

ExecutionType
PayInExecutionType

PayInExecutionType:

WEB, DIRECT, EXTERNAL_INSTRUCTION

The execution type of the payin

The type of execution for the payin

DeclaredDebitedFunds
Money

Money:

View Sub-parameters

The declared debited funds

DeclaredDebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format

The currency - should be ISO_4217 format

DeclaredDebitedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

DeclaredFees
Money

Money:

View Sub-parameters

The declared fees

DeclaredFees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format

The currency - should be ISO_4217 format

DeclaredFees.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

WireReference
string

string:

Maximum length is 255 characters

Wire reference

BankAccount
BankAccount-v2

BankAccount-v2:

View Sub-parameters

Bank account details

BankAccount.BIC
string

string:

Maximum length is 255 characters

The BIC of the bank account

BankAccount.IBAN
string

string:

Maximum length is 255 characters

The IBAN of the bank account

BankAccount.OwnerName
string

string:

Maximum length is 255 characters

The name of the owner of the bank account

BankAccount.OwnerAddress
string

string:

Maximum length is 255 characters

The address of the owner of the bank account

BankAccount.Type
BankAccountType

BankAccountType:

IBAN, GB, US, CA, OTHER

The type of BankAccount

The type of bank account

{
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"DeclaredDebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"DeclaredFees": {
"Currency": "EUR",
"Amount": 12
},
"WireReference": "iuygh0987s",
"BankAccount": {
"BIC": "BNPAFRPP",
"IBAN": "FR7630004000031234567890143",
"OwnerName": "Joe Blogs",
"OwnerAddress": "3 Mangopay Loop, Paris, 777",
"Type": "IBAN"
}
}

Create a Bankwire Direct PayIn

POST .../v2.01/ClientId

The ID of your client account

/payins/bankwire/direct/

Parameters

AuthorId
string

string:

Maximum length is 255 characters
required

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

DeclaredDebitedFunds
Money

Money:

View Sub-parameters
required

The declared debited funds

DeclaredDebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DeclaredDebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

DeclaredFees
Money

Money:

View Sub-parameters
required

The declared fees

DeclaredFees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DeclaredFees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"CreditedWalletId": "8494559",
"DeclaredDebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"DeclaredFees": {
"Currency": "EUR",
"Amount": 12
}
}
POST .../payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DeclaredDebitedFunds": {
"Currency": "",
"Amount":
},
"DeclaredFees": {
"Currency": "",
"Amount":
}
}

The Bankwire External Instruction PayIn object (BETA*)

A bankwire by "external instruction" is a slightly particular payin whereby it is created when we receive funds for a banking alias - this means there is no way of creating a payin of this kind via the API (in sandbox, please contact our support team for them to create some examples for you).

Please note DebitedBankAccount details should not be available for TARGET2 bankwires

Parameters

BankingAliasId
string

string:

Maximum length is 255 characters

The ID of a banking alias

WireReference
string

string:

Maximum length is 255 characters

Wire reference

DebitedBankAccount
DebitedBankAccount

DebitedBankAccount:

Information about the bank account that was debited

View Sub-parameters

Information about the account that was debited

DebitedBankAccount.OwnerName
string

string:

Maximum length is 255 characters

The name of the owner of the bank account

DebitedBankAccount.Type
string

string:

Maximum length is 255 characters

The type of bank account

DebitedBankAccount.IBAN
string

string:

Maximum length is 255 characters

The IBAN of the bank account

DebitedBankAccount.BIC
string

string:

Maximum length is 255 characters

The BIC of the bank account

{
"BankingAliasId": "20570432",
"WireReference": "iuygh0987s",
"DebitedBankAccount": {
"OwnerName": "Joe Blogs",
"Type": "IBAN",
"IBAN": "FR7630004000031234567890143",
"BIC": "BNPAFRPP"
}
}

The Direct-Debit Web PayIn object

A PayIn by direct debit and via web is a request to process a payment to a wallet for a dedicated user.

  • There is no possibility of recurring payment for the moment with SOFORT and GIROPAY.
  • Please use the testing accounts described here testing rules. If you use your own account even in sandbox you will actually be debited!

Parameters

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of payin

ExecutionType
PayInExecutionType

PayInExecutionType:

WEB, DIRECT, EXTERNAL_INSTRUCTION

The execution type of the payin

The type of execution for the payin

ReturnURL
string

string:

Maximum length is 255 characters

The URL to redirect to after payment (whether successful or not)

DirectDebitType
DirectDebitType

DirectDebitType:

SOFORT, GIROPAY

The type of web direct debit

The type of web direct debit

SecureMode
SecureMode

SecureMode:

DEFAULT, FORCE, NO_CHOICE

The SecureMode is used to select a 3DS1 and 3DS2 protocol for CB Visa and MasterCard. The field lets you ask for an Frictionless payment with the value "DEFAULT". The value "NO_CHOICE" will allow you to make the transaction eligible for Frictionless, but the exemption will be applied by the other payment actors. The value force "FORCE"will force customer authentification.

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage

The language to use for the payment page - needs to be the ISO code of the language

TemplateURL
string

string:

Maximum length is 255 characters

The URL to use for the payment page template

RedirectURL
string

string:

Maximum length is 255 characters

The URL to redirect to user to for them to proceed with the payment

{
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"ReturnURL": "http://www.my-site.com/returnURL/",
"DirectDebitType": "SOFORT",
"SecureMode": "DEFAULT",
"Culture": "EN",
"TemplateURL": "http://www.my-site.com/templateURL/",
"RedirectURL": "http://www.a-url.com/redirect"
}

Create a Direct-Debit Web PayIn

POST .../v2.01/ClientId

The ID of your client account

/payins/directdebit/web/

Parameters

AuthorId
string

string:

Maximum length is 255 characters
required

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

DebitedFunds
Money

Money:

View Sub-parameters
required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
required

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

ReturnURL
string

string:

Maximum length is 255 characters
required

The URL to redirect to after payment (whether successful or not)

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

DirectDebitType
DirectDebitType

DirectDebitType:

SOFORT, GIROPAY

The type of web direct debit
required

The type of web direct debit

Culture
CultureCode

CultureCode:

DE, EN, DA, ES, ET, FI, FR, EL, HU, IT, NL, NO, PL, PT, SK, SV, CS

The language to use for the payment webpage
required

The language to use for the payment page - needs to be the ISO code of the language

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/directdebit/web/ HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"ReturnURL": "http://www.my-site.com/returnURL/",
"CreditedWalletId": "8494559",
"DirectDebitType": "SOFORT",
"Culture": "EN"
}
POST .../payins/directdebit/web/ HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"CreditedUserId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"ReturnURL": "",
"CreditedWalletId": "",
"DirectDebitType": "",
"Culture": ""
}

The Direct-Debit Direct PayIn object

A PayIn by direct debit with a mandate is a request to process a payment to a wallet for a dedicated user.

Note that there is a limit of 1EUR/GBP (Min) - 2500EUR/GBP (Max) per direct debit payment – please contact your sales manager if you require a higher limit

  • To use this payin method, you must have already created and submitted a Mandate (in a similar way to doing a direct card payin)
  • Late failures: note that due to the nature of this payment method, it is possible to have a "late failure" which is when the payment Status is already "SUCCEEDED" but later on, the bank pulls back the funds and to reflect that in the API, we will create a Dispute (and hence Repudiation) with the DisputeReasonType being "LATE_FAILURE" which gives more information regarding the reason. In BACS (UK) the majority of late failures happen within 2/3 days. In SEPA, all late failures are within 5 days.

Within the SEPA (Eurozone) Direct Debit scheme, late failures are more commonly found to occur several business days following the payment charge date. As such, we recommend allowing a minimum of 8 business days following confirmation of a payment being successfully charged, before processing a refund of said payment to your customer.

  • Refunds are available for these PayIns, but you should know that a user can also dispute a payment and his bank will automatically refund it (for SEPA payments, this can be up to 8 weeks after the payment was made; for BACS, there is no time limit for a dispute) – there is no way to contest these decisions and we will create a normal Dispute
  • Payment for direct debit payins is not taken instantly, and there will therefore be a delay before the transaction has theStatus of "SUCCEEDED". In the majority of cases, the timing is as follows:
Scheme Payments with this mandat Payment is created User notified Payment becomes "SUCCEEDED"
SEPA 1st+ payment D+0 D+0 D+5
BACS 1st payment D+0 D+1 D+6
BACS 2nd+ payment D+0 D+0 D+5
  • As with the submission of a mandate, we will notify the user of all upcoming payments on your behalf (the design of this email can be lightly customised – see here)
  • For testing payments, you should use a specific value for the FirstName of the user owning the mandate
    1. "Successful" will result in a successful payment
    2. "Penniless" will result in a failed payment due to lack of funds
    3. "Fickle" will result in a successfull payment, which is disputed by the user and hence a dispute is created
  • Mandate and direct debit payins are only available for certain business types, and is not activated by default – please contact your sales manager for more info
  • For BACS payments, you should know that the banks Natwest, RBS, HSBC, Metro and Nationwide will not show your client name with payments, and only "MANGOPAY" will be shown

You should be very careful when refunding these direct debit payments because chargebacks (disputes) are non-contestable, therefore if the end-user also requests a chargeback to their bank for a payment you have already refunded, you will have to cover the disputed funds yourself (since the funds of the original payment have already been refunded).

Parameters

MandateId
string

string:

Maximum length is 255 characters

The ID of a Mandate

ChargeDate
timestamp

timestamp

The date the user will be charged. Note that for direct debit payments, it will take one more day more the payment becomes successful

StatementDescriptor
string

string:

up to 10 characters

A custom description to appear on the user's bank statement. It can be up to 100 characters long, and can only include alphanumeric characters or spaces. See here for important info and note that this functionality is only available for SEPA payments.

{
"MandateId": "24733034",
"ChargeDate": 1494350900,
"StatementDescriptor": "Nov2016"
}

Create a Direct-Debit Direct PayIn

POST .../v2.01/ClientId

The ID of your client account

/payins/directdebit/direct/

Parameters

AuthorId
string

string:

Maximum length is 255 characters
required

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

CreditedWalletId
string

string:

Maximum length is 255 characters
required

The ID of the wallet where money will be credited

DebitedFunds
Money

Money:

View Sub-parameters
required

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
required

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

MandateId
string

string:

Maximum length is 255 characters
required

The ID of a Mandate

StatementDescriptor
string

string:

up to 10 characters
optional

A custom description to appear on the user's bank statement. It can be up to 100 characters long, and can only include alphanumeric characters or spaces. See here for important info and note that this functionality is only available for SEPA payments.

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../payins/directdebit/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"CreditedWalletId": "8494559",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"MandateId": "24733034",
"StatementDescriptor": "Nov2016"
}
POST .../payins/directdebit/direct/ HTTP/1.1
Body Parameters :
{
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"MandateId": "",
"StatementDescriptor": ""
}

Create a Bankwire PayIn to your Client Credit Wallet

It is possible to add funds to your Credit/Repudiation Wallets via a PayIn Bankwire in order to settle the funds after a dispute. This endpoint can be used only for this purpose. For more information check The Settement Transfer object on the doc

POST .../v2.01/ClientId

The ID of your client account

/clients/payins/bankwire/direct/

Parameters

CreditedWalletId
ClientWalletAlias

ClientWalletAlias:

FEES_EUR, CREDIT_EUR, FEES_USD, CREDIT_USD, FEES_GBP, CREDIT_GBP, ...

An alias for a client wallet - made up from the FundsType and the Currency - "FEES_EUR" would therefore give the client's FEES wallet for EUR
required

The ID of the wallet where money will be credited

DeclaredDebitedFunds
Money

Money:

View Sub-parameters
required

The declared debited funds

DeclaredDebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DeclaredDebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
POST .../clients/payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"CreditedWalletId": "CREDIT_EUR",
"DeclaredDebitedFunds": {
"Currency": "EUR",
"Amount": 12
}
}
POST .../clients/payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"CreditedWalletId": "",
"DeclaredDebitedFunds": {
"Currency": "",
"Amount":
}
}

The PayIn Web Extended Object

The Pay-in web extended view is a view to get more details about the card used to process a payin web.

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of payin

ExecutionDate
timestamp

timestamp

When the transaction happened

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

CardType
CardType

CardType:

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

The type of Card

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

Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format

The Country of the Address

Fingerprint
string

string:

Maximum length is 255 characters

A unique representation of a 16-digits card number

{
"Id": "8494514",
"PaymentType": "CARD",
"ExecutionDate": 1463496101,
"ExpirationDate": "1019",
"Alias": "497010XXXXXX4414",
"CardType": "CB_VISA_MASTERCARD",
"Country": "FR",
"Fingerprint": "50a6a8da09654c4cab901814a741f924"
}

View card details for a PayIn Web

Note that this endpoint is only available for PayIn:

  • through Web interface
  • when customer has provided some Card infos
GET .../v2.01/ClientId

The ID of your client account

/payins/card/web/PayInId

The Id of a PayIn

/extended/
  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../payins/card/web/:PayInId/extended/ HTTP/1.1
GET .../payins/card/web//extended/ HTTP/1.1

View a PayIn

GET .../v2.01/ClientId

The ID of your client account

/payins/PayInId

The Id of a PayIn

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../payins/:PayInId/ HTTP/1.1
GET .../payins// HTTP/1.1

The Recurring PayIn Registration object

This feature is in preview and is not yet available in production.

The Recurring PayIn Registration object lets you register a recurring payment. Payments made using this object can be requested using the Recurring PayIn object. The process is as follows:

  1. Create a Recurring PayIn Registration object
  2. Request a first and subsequent Recurring PayIns using the RecurringPayinRegistrationId.

Please refer to the recurring payments page for more information.

Create a Recurring PayIn Registration

This feature is in preview and is not yet available in production.

POST .../v2.01/ClientId

The ID of your client account

/recurringpayinregistrations

Parameters

AuthorId
string

string:

Maximum length is 100 characters
required

A user's ID

CardId
string

string:

Maximum length is 100 characters
required

The ID of a card

CreditedUserId
string

string:

Maximum length is 100 characters
optional

The user ID who is credited (defaults to the owner of the wallet)

CreditedWalletId
string

string:

Maximum length is 100 characters
required

The ID of the wallet where money will be credited

FirstTransactionDebitedFunds
Money

Money:

View Sub-parameters
required

Amount of the first payment. This amount may be different from the NextTransactionDebitedFunds.

FirstTransactionDebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

FirstTransactionDebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

FirstTransactionFees
Money

Money:

View Sub-parameters
required

Amount of the first payment fees. This amount may be different from the NextTransactionFees.

FirstTransactionFees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

FirstTransactionFees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Billing
Billing

Billing:

View Sub-parameters
required

Contains every useful informations related to the user billing

Billing.FirstName
string

string:

Maximum length is 255 characters
required

The name of the user

Billing.LastName
string

string:

Maximum length is 255 characters
required

The last name of the user

Billing.Address
Address

Address:

View Sub-parameters
required

The address

Billing.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Billing.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Billing.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Billing.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Billing.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Billing.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

Shipping
Shipping

Shipping:

View Sub-parameters
required

Contains every useful information's related to the user shipping

Shipping.FirstName
string

string:

Maximum length is 100 characters
required

The name of the user

Shipping.LastName
string

string:

Maximum length is 100 characters
required

The last name of the user

Shipping.Address
Address

Address:

View Sub-parameters
required

The address

Shipping.Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Shipping.Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Shipping.Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Shipping.Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Shipping.Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Shipping.Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

EndDate
timestamp

timestamp
optional

Date on which the recurring payments will end

Frequency
string

string:

Daily | Weekly | TwiceAMonth | Monthly | Bimonthly | Quarterly | Semiannual |Annual | Biannual
optional

Frequency at which the recurring payments will be made

FixedNextAmount
bool

bool:

true, false
optional

Indicates whether the payment amount is likely to change during the payment period

FractionedPayment
bool

bool:

true, false
optional

Indicates whether this recurring payment is a payment in installments in N times

Migration
bool

bool:

true, false
optional

Indicates whether the object is being used to attempt registration of an existing recurring payment

NextTransactionDebitedFunds
Money

Money:

View Sub-parameters
optional

Amount of subsequent payments. If this field is empty and either FixedNextAmount or FractionedPayment are TRUE, we will take the amount of the FirstTransactionDebitedFunds as the subsequent payment amount.

NextTransactionDebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

NextTransactionDebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

NextTransactionFees
Money

Money:

View Sub-parameters
optional

Amount of subsequent fees. If this field is empty and either FixedNextAmount or FractionedPayment are TRUE, we will take the amount of the FirstTransactionFees as the subsequent fees.

NextTransactionFees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

NextTransactionFees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
POST .../recurringpayinregistrations HTTP/1.1
Body Parameters :
{
"AuthorId": "8494514",
"CardId": "14213157",
"CreditedUserId": "8494514",
"CreditedWalletId": "8494559",
"FirstTransactionDebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"FirstTransactionFees": {
"Currency": "EUR",
"Amount": 12
},
"Billing": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Shipping": {
"FirstName": "Joe",
"LastName": "Blogs",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"EndDate": 1463494366,
"Frequency": "Daily",
"FixedNextAmount": true,
"FractionedPayment": true,
"Migration": true,
"NextTransactionDebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"NextTransactionFees": {
"Currency": "EUR",
"Amount": 12
}
}

The Recurring PayIn object

This feature is in preview and is not yet available in production.

A Recurring PayIn can be requested once you have created a Recurring PayIn Registration and obtained a RecurringPayinRegistrationId.

The first Recurring PayIn is authenticated by the cardholder via the 3DS protocol. This payment is a customer-initiated transaction (CIT).

Subsequent Recurring PayIns are made in the absence of the cardholder and are not authenticated. These payments are merchant-initiated transactions (MIT).

The same endpoint is used for both transaction types, with differences in the information supplied.

Please refer to the recurring payments page for more information.

Create a Recurring PayIn CIT

POST .../v2.01/ClientId

The ID of your client account

/payins/recurring/card/direct

Parameters

RecurringPayinRegistrationId
string

string:

Maximum length is 100 characters
required

The recurring's ID

BrowserInfo
BrowserInfo

BrowserInfo:

This object describes the Browser being user by an end user

View Sub-parameters
required

This object describes the Browser being user by an end user

BrowserInfo.AcceptHeader
string

string:

Maximum length is 255 characters
required

Exact content of the HTTP accept headers as sent to the merchant from the shopper’s browser

BrowserInfo.JavaEnabled
bool

bool:

true, false
required

Whether the user browser has Java enabled

BrowserInfo.Language
string

string:

Maximum length is 255 characters
required

Language of the browser of the user

BrowserInfo.ColorDepth
int

int
required

Value representing the bit depth of the colour palette for displaying images, in bits per pixel

BrowserInfo.ScreenHeight
int

int
required

The height of the screen in pixels

BrowserInfo.ScreenWidth
int

int
required

The width of the screen in pixels

BrowserInfo.TimeZoneOffset
string

string:

Maximum length is 12 characters
required

UTC time offset in minutes

BrowserInfo.UserAgent
string

string:

Maximum length is 255 characters
required

Exact content of the HTTP user-agent header

BrowserInfo.JavascriptEnabled
bool

bool:

true, false
required

Whether the browser is Javascript enabled

IpAddress
string

string:

Maximum length is 100 characters
required

IP Address of the end user (format IPV4 or IPV6)

SecureModeReturnURL
string

string:

Maximum length is 100 characters
required

This is the URL where users are automatically redirected after 3D secure validation (if activated)

StatementDescriptor
string

string:

Maximum length is 100 characters
optional

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

Tag
string

string:

Maximum length is 100 characters
optional

Custom data that you can add to this item

  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
POST .../payins/recurring/card/direct HTTP/1.1
Body Parameters :
{
"RecurringPayinRegistrationId": "lorem",
"BrowserInfo": {
"AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
"JavaEnabled": true,
"Language": "FR-FR",
"ColorDepth": 4,
"ScreenHeight": 1800,
"ScreenWidth": 400,
"TimeZoneOffset": "+60",
"UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
"JavascriptEnabled": true
},
"IpAddress": "2001:0620:0000:0000:0211:24FF:FE80:C12C",
"SecureModeReturnURL": "http://www.my-site.com/returnURL",
"StatementDescriptor": "lorem",
"Tag": "custom meta"
}

Create a Recurring PayIn MIT

POST .../v2.01/ClientId

The ID of your client account

/payins/recurring/card/direct

Parameters

RecurringPayinRegistrationId
string

string:

Maximum length is 100 characters
required

The recurring's ID

DebitedFunds
Money

Money:

View Sub-parameters
optional

Amount of the subsequent payment. If this field is empty we will take the amount entered in the NextTransactionDebitedFunds of the Recurring PayIn Registration. An amount must be transmitted during either registration or pay-in (if it’s different from the registration one).

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters
optional

Amount of the subsequent fees. If this field is empty we will take the amount entered in the NextTransactionFees of the Recurring PayIn Registration. An amount must be transmitted during either registration or pay-in.

Fees.Currency
CurrencyIso

CurrencyIso:

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

ISO 4217 format
required

The currency - should be ISO_4217 format

Fees.Amount
int

int
required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

StatementDescriptor
string

string:

Maximum length is 100 characters
optional

A custom description to appear on the user's bank statement. It can be up to 10 characters long, and can only include alphanumeric characters or spaces. See here for important info. Note that each bank handles this information differently, some show less or no information.

Tag
string

string:

Maximum length is 100 characters
optional

Custom data that you can add to this item

  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
  • View
  • Code
    A code sample is not available
  • Run
    A demo is not available
POST .../payins/recurring/card/direct HTTP/1.1
Body Parameters :
{
"RecurringPayinRegistrationId": "lorem",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"StatementDescriptor": "lorem",
"Tag": "custom meta"
}
Share feedback
Live chat
No agent is free at the moment please send us a request through our contact form
CONTACT FORM