PAYMENT

Single Payment

A one-off transaction is a transaction that uses a debit/credit card for a single payment. There are two ways to process a debit/credit card in a one-off transaction:

Use the sub-object « Card[*] »: it is necessary to fill in all the information of the card,

Use the field « cardTokenId »: we use a unique token to identify the card

Note: in this case, "Card" can only be used once.

« RECURRING » Payment

To process recurring transactions, first create a "Customer" and one or several "Cards" associated to this "Customer":

Create a « Customer » object: it acts like an e-wallet including one or several cards (via token or not)

AND

Use the « customerId » field: this links the payment to a client

Note: in this case, "Cards" can be used several times.

Card token

The Json "CardToken" object

The « CardToken » object represents a debit/credit card token.

Merchants usually want to be able to charge payment cards, IBAN or other without having to store sensitive data on their servers.
Token.js makes this easy in the browser, but you can use the same technique in other environments with our token API.

Tokens can be created with your publishable API key, which can safely be embedded in downloadable applications like iPhone and Android apps. You can then use a token anywhere in our API when a credit/debit card, bank account or any personal ID number is accepted.

Body Parameters
cardTokenId String (36)	CentralPay token ID Note: UUID Format
creationDate String	Creation date Note: ISO 8601
card Card object	Card Note: Refer to the JSON "Card" object
endUserIp String	End-user IP
status String	Token use status Note: UNUSED \| USED \| EXPIRED

HTTP Request

POST https://test-api.centralpay.net/v2/rest/cardToken

Body Parameters
card[]	Card data Required: yes Child arguments : - Required: yes - card[number]=string without any separators - Required: yes - card[expirationMonth]=2 digit - Required: yes - card[expirationYear]=2 or 4 digit - Required: no - card[cvc]= cvc of the card - Required: no - card[country]= string alpha 3 code of the card country - Required: no - card[description]= Merchant description for the card - Required: no - card[holderName]=Cardholder name - Required: no - card[holderEmail]=Cardholder email - [Deprecated] Required: no - card[check]=Check if card should be verified at customer creation
merchantPublicKey String	CentralPay Merchant's public key Required: yes Validation: [0-9a-f]{64} - Key needs to match with a merchant Note: This key is provided by CentralPay

Body Parameters
currency String (3)	Currency Required: yes Validation: ISO4217 alpha format or num [A-Z}{3}\|[0-9]{3} Existing Authorised (for the contract)
amount Integer	Total amount of the transaction Required: yes Validation: > 0 and <= 9999999 Add limits (min/max) by contract Validation: 0 if source = RI Note: In cents
endUserIp String (39)	Card holder Ip address Required: yes
customerId UUID (36)	CentralPay client ID Required: conditional Validation: UUID - Existing - Authorised (for the user)
cardId UUID (36)	CentralPay card ID Required: conditional Validation: UUID - Existing - Authorised (for the customer) Note: customerID required
cardTokenId UUID (36)	CentralPay token ID Required: conditional Validation: UUID - Existing - Authorised (for the user) - Status UNUSED
card[*] (deprecated)	Card data Required: conditional Note: Refer to "Card" sub-object
otp String	OTP Validation Required: conditional Note: use to send the OTP when a customerId is used in a 1-click transaction for example
cvcValidation String	CVC Validation Required: conditional Note: use to send the CVC when a customerId is used in a 1-click transaction for example
merchantTransactionId String (100)	Merchant ID Required: no Validation: .{0,100}
pointOfSaleId UUID (36)	CentralPay POS ID Required: no Validation: UUID - Existing - Authorised for the user
contractId UUID (36)	CentralPay contract ID Required: no Validation: UUID - Existing - Authorised for the PoS
source Enum source	Payment source Required: no Validation: EC \| MO \| TO \| DP \| RI Note: EC: Electronic Commerce MO: Mail Order TO: Telephone Order RI: Request Information - Zero amount autorization (amount = 0 is required) DP: Deposit EC by default when the used card has been registered with a cvc in our systems TO by default when the used card has been registered without a cvc in our systems
description String (256)	Description Required: no Validation: .{0,256}
capture Boolean	Indicate if the transaction has to be debited Required: no Validation: true \| false Notes: True by default Can not capture by default if the source is DP
country Country	Merchant's Country Required: no Validation: ISO3166 in format alpha2, apha3 or num - [0-9]{3}\|[A-Z]{2}\|[A-Z]{3} - Existing
endUserLanguage	End user's language Required: no Validation: ISO 639-2 (3 char) ou ISO 639-1 (2 char) Default value: ENG
receiptEmail String (255)	Email to send the receipt Required: no Validation: Email Note: Receipt email sent to this address, once the transaction is debited. By default, if the transaction is linked to a client, that is the client's email that will be used. If this parameter is given, it is used instead of client's one. If endUserLanguage is not used, then default value applied
rate Number	Pay rates Required: no Validation: Between 0 and 100 Note: In percentage
browserUserAgent String (255)	HTTP header user-agent of the client's browserRequired: no
browserAcceptLanguage String (255)	HTTP header accept-language of the client's browserRequired: no
customAcceptanceData Map <String,string>	Custom field for data acceptance The size of this field must not exeed 3 Required: no
order[*]	Data of the order Required: no Note: Refer to "Order" sub-object
3ds[*]	3-D Secure data Required: no Note: Refer to "3ds" sub-object
transferGroup String (100)	Transfer group identifierRequired: no
scaExterne String	Indicate if this is an External SCA. Value : True or FalseRequired: no
scaExterneDsTransId UUID	DsTransId from 3ds 2.0.Required: no
scaExterneAcsTransId UUID	AcsTransId from 3ds 2.0. Required: no
additionalData String (303)	Merchant data Required: no Validation: Key: .{45} - Value: .{256} Sample: additionalData=[Key]Value Note: Number of key/value combinations because can take multiple keys and values. You can add as many additionnalData parameters as you need.
additionalDataPrivate[bdkName] String	The BDK (Base Derivation Key) Name is used to send the identifier of the BDK key from which the PIN encryption key is derived.Required: no
additionalDataPrivate[bdkVersion] String	Version used for the BDK.Required: no
additionalDataPrivate[ksn] String	Key Serial Number used when pin is encoded using DUKPT.Required: no
partialAuthorization Boolean	Partial authorizationRequired: no
receiptEmail String	Receipt email of the transactionRequired: no
paymentRequestBreakdownId UUID	Identifier of the payment request breakdownRequired: no
totalAmount Integrer	Total amount (in cents) of the transactionRequired: no
transfer[] Arrray	Transfer to do with the transaction Exemple : `{"destinationWalletId":"bba1c2fa-9047-48fe-a6f3-2d8d4c296168","currency":"EUR","fee":0,"amount":2500,"escrowDate":"2024-02-03"}`Required: no
walletId UUID	Identifier of the wallet.Required: no

Body Parameters
transactionId UUID (36)	CentralPay ID of the transaction Required: yes
description String (256)	Description Required: no Validation: .{0,256}
merchantTransactionId String (100)	Merchant ID Required: no Validation: .{0,100}
transferGroup String (100)	Transfer group identifier Required: no Validation: .{0,100}
receiptEmail String (255)	Email to send the receipt Required: no Validation: Email
additionalData String (303)	Merchant data Required: no Validation: Key : .{45} - Value : .{256} Sample : additionalData=[Key]Value Note: Number of key/value combinations as it can have multiple keys and values.

Body Parameters
transactionId UUID (36)	CentralPay ID of the transaction Required: yes Validation: UUID - Existing - Authorised (for the user) Note: The transaction SHOULD be: - authorizationStatus = SUCCESS - captureStatus = UNCAPTURED - must be less than 7 days if source in (EC, MO, TO) - must be less than 30 days if source = DP
amount Integer	Amount of debit Required: no Validation: > 0 and <= amount authorisation Note: Amount of the authorisation by default
walletId UUID	Identifier of the wallet. Required: no