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

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 All Card
Maestro alt Yes Yes Always 3DS Yes EUR Card
Diners alt Yes Yes No Yes EUR Card
MasterPass alt Yes No No Yes All 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

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

Fees
Money

Money:

View Sub-parameters

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

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

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

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

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of pay-in

ExecutionType
PayInExecutionType

PayInExecutionType:

WEB, DIRECT, EXTERNAL_INSTRUCTION

The execution type of the payin

The type of execution for the payin

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "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

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

Fees
Money

Money:

View Sub-parameters

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

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

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

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

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of pay-in

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)

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

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

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.

RedirectURL
string

string:

Maximum length is 255 characters

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

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "PAYIN",
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"ReturnURL": "http://www.my-site.com/returnURL/",
"CardType": "CB_VISA_MASTERCARD",
"SecureMode": "DEFAULT",
"Culture": "EN",
"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.

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

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

The type of Card
required

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

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:

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.

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../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"
}
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": ""
}

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)

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

SecureModeNeeded
bool

bool:

true, false

The value is 'true' if the SecureMode was used

SecureModeRedirectURL
string

string:

Maximum length is 255 characters

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

{
"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"
},
"Culture": "EN",
"SecureModeNeeded": false,
"SecureModeRedirectURL": "http://www.a-url.com/3DS-redirect"
}

Create a Card Direct PayIn

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

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../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"
}
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": ""
}

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

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

POST .../v2/ClientId

The ID of your client account

/payins/preauthorized/direct/

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)

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../payins/preauthorized/direct/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"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 :
{
"Tag": "",
"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

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

Fees
Money

Money:

View Sub-parameters

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

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

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

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

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of pay-in

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
Currency

Currency:

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

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
Currency

Currency:

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

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

BankAccount:

View Sub-parameters

Bank account details

BankAccount.BIC
string

string:

Maximum length is 255 characters

The BIC of the bank account. The BIC (international identifier of the bank) can have one of the two following formats:

  1. BIC8 – 8-character BIC (AAAABBCC)
  2. BIC11 – 11-character BIC (AAAABBCCDDD)

In which:

  • AAAA stands for the bank code: 4 characters defining the bank
  • BB stands for the country code: 2 characters forming the country ISO code (ISO 3166 format)
  • CC stands for the location code: 2 localization characters (alphabetical or numeric) to distinguish banks from the same country
  • DDD stands for the branch code: 3 optional characters defining the branch as a branch of the bank
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
Address

Address:

View Sub-parameters

The address of the owner of the bank account

BankAccount.OwnerAddress.AddressLine1
string

string:

Maximum length is 255 characters

The first line of the address

BankAccount.OwnerAddress.AddressLine2
string

string:

Maximum length is 255 characters

The second line of the address

BankAccount.OwnerAddress.City
string

string:

Maximum length is 255 characters

The city of the address

BankAccount.OwnerAddress.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

BankAccount.OwnerAddress.PostalCode
string

string:

Maximum length is 50 characters

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

BankAccount.OwnerAddress.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

BankAccount.Type
BankAccountType

BankAccountType:

IBAN, GB, US, CA, OTHER

The type of BankAccount

The type of bank account

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "PAYIN",
"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": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
},
"Type": "IBAN"
}
}

Create a Bankwire Direct PayIn

POST .../v2/ClientId

The ID of your client account

/payins/bankwire/direct/

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)

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"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 :
{
"Tag": "",
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DeclaredDebitedFunds": {
"Currency": "",
"Amount":
},
"DeclaredFees": {
"Currency": "",
"Amount":
}
}

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. These payments are available only for Germany.
  • Please use the testing accounts described here testing rules. If you use your own account even in sandbox you will actually be debited!

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

Fees
Money

Money:

View Sub-parameters

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

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

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

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

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of pay-in

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

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "PAYIN",
"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/ClientId

The ID of your client account

/payins/directdebit/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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

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

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../payins/directdebit/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/",
"CreditedWalletId": "8494559",
"DirectDebitType": "SOFORT",
"SecureMode": "DEFAULT",
"Culture": "EN",
"TemplateURLOptions": {
"PaylineV2": "https://www.mysite.com/template/"
}
}
POST .../payins/directdebit/web/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"AuthorId": "",
"CreditedUserId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"ReturnURL": "",
"CreditedWalletId": "",
"DirectDebitType": "",
"SecureMode": "",
"Culture": "",
"TemplateURLOptions": {
"PaylineV2": ""
}
}

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 2500EUR/GBP 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.
  • 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+4
BACS 1st payment D+0 D+1 D+5
BACS 2nd+ payment D+0 D+0 D+4
  • 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

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
Currency

Currency:

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

The currency - should be ISO_4217 format

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

Fees
Money

Money:

View Sub-parameters

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

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

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

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

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

PaymentType
PayInPaymentType

PayInPaymentType:

CARD, DIRECT_DEBIT, PREAUTHORIZED, BANK_WIRE

The payment type of the payin

The type of pay-in

ExecutionType
PayInExecutionType

PayInExecutionType:

WEB, DIRECT, EXTERNAL_INSTRUCTION

The execution type of the payin

The type of execution for the payin

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:

Maximum length is 255 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.

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "PAYIN",
"PaymentType": "CARD",
"ExecutionType": "DIRECT",
"MandateId": "24733034",
"ChargeDate": 1494350900,
"StatementDescriptor": "Nov2016"
}

Create a Direct-Debit Direct PayIn

POST .../v2/ClientId

The ID of your client account

/payins/directdebit/direct/

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)

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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:

Maximum length is 255 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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../payins/directdebit/direct/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"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 :
{
"Tag": "",
"AuthorId": "",
"CreditedUserId": "",
"CreditedWalletId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
},
"MandateId": "",
"StatementDescriptor": ""
}

Create a Bankwire PayIn to a Client Wallet

It is possible to add funds to your Credit Wallets via a PayIn Bankwire

POST .../v2/ClientId

The ID of your client account

/clients/payins/bankwire/direct/

Parameters

Tag
string

string:

Maximum length is 255 characters
optional

Custom data that you can add to this item

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
Currency

Currency:

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

The currency - should be ISO_4217 format

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
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../clients/payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"CreditedWalletId": "CREDIT_EUR",
"DeclaredDebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"DeclaredFees": {
"Currency": "EUR",
"Amount": 12
}
}
POST .../clients/payins/bankwire/direct/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"CreditedWalletId": "",
"DeclaredDebitedFunds": {
"Currency": "",
"Amount":
},
"DeclaredFees": {
"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 pay-in

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

The ID of your client account

/payins/card/web/PayInId

The Id of a PayIn

/extended/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../payins/card/web/:PayInId/extended/ HTTP/1.1
GET .../payins/card/web//extended/ HTTP/1.1

View a PayIn

GET .../v2/ClientId

The ID of your client account

/payins/PayInId

The Id of a PayIn

/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../payins/:PayInId/ HTTP/1.1
GET .../payins// HTTP/1.1
Share feedback