Introduction
 |
Ratepay offers merchants and marketplaces in German-speaking countries the opportunity to integrate the "Buy Now, Pay Later" (BNPL) payment methods invoice, installment payment and direct debit as payment methods in their online store. In doing so, Ratepay assumes the full fraud and default risk and supports merchants throughout the entire value chain from integration assistance to collection handover. The central component is a self-learning scoring and risk model that identifies fraudsters. |
Integrations
POST Request - Pre-/ Authorization
Specials are:
- genericPayment(calculation) is used for the calculation of installment plans - genericPayment(profile) is used for retrieval of account settings from Ratepay
Account Parameters
|
request
required
|
Fixed Value: preauthorisation/authorization
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common Parameters
|
clearingtype
required
|
Fixed Value fnc
|
|
financingtype
required
|
Fixed Value RPV, RPD, RPS
RPV: Ratepay Open Invoice RPD: Ratepay Direct Debit RPS: Ratepay Installments |
|
reference
required
|
Format CHAR(1..20)
Permitted Symbols [0-9][a-z][A-Z], .,-,_,/
Merchant reference number for the payment process (case insensitive) |
|
amount
required
|
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99
Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro. The amount must be less than or equal to the amount of the corresponding booking. |
|
currency
required
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP |
|
narrative_text
optional
|
Format CHAR(1..81)
Dynamic text element on account statements (3 lines with 27 characters each) and credit card statements. |
Personal Data Parameters
|
firstname
required
|
Format CHAR(1..50)
First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname" |
|
lastname
required
|
Format CHAR(2..50)
Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname" |
|
company
optional
|
Format CHAR(2..50)
Company name, required for B2B transactions (if add_paydata[b2b] = “yes”) |
|
street
required
|
Format CHAR(1..50)
Street number and name (required: at least one character) |
|
zip
required
|
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]
Postcode |
|
city
required
|
Format CHAR(2..50)
City of customer |
|
country
required
|
Format LIST
Permitted values ISO 3166 2-letter-codes
Samples
DE GB US Specifies country of address for the customer. Some countries require additional information in parameter "state"
|
|
email
required
|
Format CHAR(5..254)
Permitted Symbols RFC 5322
Special Remark email validation: Max. length for email is 254 characters. Validation is set up in the following way: Username = Max. 63 characters Domain Name = Max. 63 characters Domain Suffixes = Max. 4 suffixes with max. 124 characters.Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4] "@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters. email-address of customer |
|
birthday
required
|
Format DATE(8), YYYYMMDD
Samples
20190101 19991231 Date of birth of customer |
|
telephonenumber
required
|
Telephone number |
Bank transfer parameter
|
bankcountry
required
|
Format LIST
Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE
DE: Mandatory with bankcode, bankaccount, optional with IBAN For other countries than DE please use IBAN or IBAN/BIC |
|
iban
optional
|
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]
Bank Identifier Code to be used for payment or to be checked |
|
bic
optional
|
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]
BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. |
Article Parameters
|
it[n]
required
|
Format LIST
|
||||||||||
|
id[n]
required
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/
International Article Number (EAN bzw. GTIN) Product number, SKU, etc. of this item |
||||||||||
|
pr[n]
required
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||||||
|
no[n]
required
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||||||
|
de[n]
required
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer. |
add_paydata PARAMETERS
|
add_paydata[shop_id]
required
|
Shop ID for the relevant Ratepay Channel. You will receive the shop_ids from Ratepay |
|
add_paydata[customer_allow_credit_inquiry]
required
|
Legacy field, please always pass "yes" |
|
add_paydata[device_token]
optional
|
Token associating the gathered customer’s device-data with the current transaction |
|
add_paydata[debit_paytype]
optional
|
Mandatory for financingtype=RPS, one of: - DIRECT-DEBIT - BANK-TRANSFER |
|
add_paydata[vat_id]
optional
|
Sending this information can increase the acceptance rate. Company VAT ID |
|
add_paydata[company_id]
optional
|
Sending this information can increase the acceptance rate. The customer’s company-ID (German “Handelsregisternummer”) |
|
add_paydata[registry_location]
optional
|
Mandatory if transaction is B2B City of the company’s register court |
|
add_paydata[company_type]
optional
|
Mandatory if transaction is B2B Refer to appendix 3.1. “company types” for values |
|
add_paydata[homepage]
optional
|
Mandatory if transaction is B2B |
|
add_paydata[registry_country_code]
optional
|
Mandatory if registry address is provided Country code ISO-3166 alpha 2 |
|
add_paydata[registry_city]
optional
|
Mandatory if registry address is provided Company registry city |
|
add_paydata[registry_zip]
optional
|
Mandatory if registry address is provided, includes number Company registry ZIP |
|
add_paydata[registry_street]
optional
|
Mandatory if registry address is provided Company registry street |
|
add_paydata[installment_amount]
optional
|
General amount the customer has to pay each month in smallest currency unit (e.g. cents) Required for RPS |
|
add_paydata[installment_number]
optional
|
Number of months for which the customer must pay the installment-amount Required for RPS |
|
add_paydata[last_installment_amount]
optional
|
Amount of the last installment bank transfer in smallest currency unit (e.g. cents) Required for RPS |
|
add_paydata[interest_rate]
optional
|
Interest rate of this installment Required for RPS Does not accept decimal values, multiply the return value from a calculation Request by 100 and pass as integer. |
|
add_paydata[amount]
optional
|
Mandatory for RPS: Total amount including service charges and interest in smallest currency unit (e.g. cents). This is returned in the response of a preceding calculation request in add_paydata[total-amount] |
|
add_paydata[referenceid]
optional
|
Can be used to submit additional merchant reference to ratepay. This field will be sent to ratepay as <reference-id>. AN..255 |
|
add_paydata[merchant_consumer_id]
optional
|
Consumer identifier for internal ratepay use. AN..100 |
Response Parameters
|
status
required
|
Permitted Values
APPROVED
ERROR
|
Response Parameter (Approved)
|
txid
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
userid
|
Format NUMERIC(9..12)
PAYONE User ID, defined by PAYONE |
|
add_paydata[clearing_reference]
|
Format CHAR(2..1024)
Accounting number, used to print on the invoice |
Response Parameter (Error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
Format CHAR(1..1024)
The customermessage is returned to your system in order to be displayed to the customer. (Language selection is based on the end customer's language, parameter "language") |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
Payload
add_paydata[customer_allow_credit_inquiry]=yes
add_paydata[device_token]=ratepay
add_paydata[merchant_consumer_id]=2
add_paydata[shop_id]=88880103
aid=52078
amount=7100
api_version=3.10
birthday=19701010
city=Dresden
clearingtype=fnc
country=DE
currency=EUR
de[1]=Belt
de[2]=Cap
de[3]=Kostenlose Lieferung
email=test@payone.com
encoding=UTF-8
financingtype=RPV
firstname=Marion
id[1]=belt
id[2]=cap
id[3]=1
it[1]=goods
it[2]=goods
it[3]=shipment
key=19539eb4b369b29f314b51368076475a
lastname=RateInv
mid=14648
mode=test
no[1]=1
no[2]=1
no[3]=1
portalid=2037267
pr[1]=5500
pr[2]=1600
pr[3]=0
reference=1242401413.1
request=preauthorization
shipping_city=Dresden
shipping_country=DE
shipping_firstname=Marion
shipping_lastname=RateInv
shipping_street=Albertplatz 3
shipping_zip=01099
street=Albertplatz 3
telephonenumber=01752345678
va[1]=0
va[2]=0
va[3]=0
zip=01099
RESPONSE
status=APPROVED
add_paydata[reservation_txid]=TX1A7DKJC9ZQ92MG
add_paydata[workorderid]=WX1A7DKJC9ZU50YW
add_paydata[clearing_reference]=KA0184106D8
txid=1082772600
userid=734183477
POST Request Capture
The capture request is used to finalize a preauthorized transaction.
If you use preauth/Capture with installment transactions, the capture request has to be sent right after the preauthorization
Account Parameters
|
request
required
|
Fixed Value: preauthorisation/authorization
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common Parameters
|
txid
required
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
||||||
|
clearingtype
required
|
Fixed Value fnc
|
||||||
|
financingtype
required
|
Fixed Value RPV, RPD, RPS
RPV: Ratepay Open Invoice RPD: Ratepay Direct Debit RPS: Ratepay Installments |
||||||
|
capturemode
required
|
Format LIST
Specifies whether this capture is the last one or whether there will be another one in future. |
||||||
|
sequencenumber
optional
|
Format NUMERIC(1..3)
Permitted values 0..127
Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2 Required for multi partial capture (starting with the 2nd capture) |
||||||
|
amount
required
|
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99
Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro The amount must be less than or equal to the amount of the corresponding booking. |
||||||
|
currency
required
|
Fixed Value EUR
|
||||||
|
narrative_text
optional
|
Format CHAR(1..81)
Dynamic text element on account statements (3 lines with 27 characters each) and credit card statements. |
add_paydata PARAMETERS
|
add_paydata[shop_id]
optional
|
Ratepay Shop ID for current transaction type If no shop_id is submitted within the capture-request, the shop_id of the preauthorization-request of that txid will be retrieved. |
|
add_paydata[tracking_provider_[n]]
optional
|
Delivery provider, check appendix 3.2. “delivery provider mapping” for possible values “tracking_provider” and “tracking_id” must be provided for same [n] |
|
add_paydata[tracking_id_[n]]
optional
|
Tracking ID of delivery item “tracking_provider” and “tracking_id” must be provided for same [n] |
|
add_paydata[referenceid]
optional
|
Format AN..255
Can be used to submit additional merchant reference to ratepay. This field will be sent to ratepay as <reference-id>. |
|
add_paydata[merchant_consumer_id]
optional
|
Format AN..100
Consumer identifier for internal ratepay use. |
Article Parameters
|
it[n]
required
|
Format LIST
Parameter it[n] specifies the item type of a shopping cart item. |
||||||||||
|
id[n]
required
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/
International Article Number (EAN bzw. GTIN) Product number, SKU, etc. of this item |
||||||||||
|
pr[n]
required
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||||||
|
no[n]
required
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||||||
|
de[n]
required
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer. |
||||||||||
|
va[n]
optional
|
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) value < 100 = percent value > 99 = basis points (e.g. 1900 = 19%) |
Response Parameters
|
status
|
Permitted Values
APPROVED
ERROR
|
Response Parameter (approved)
|
txid
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
add_paydata[clearing_reference]
|
Accounting number, used to print on the invoice (only for API version >3.10) |
Response parameters (error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
POST Request Debit
Refund with Ratepay can currently only be ordered via this API, not via the PMI.
Account Parameters
|
request
required
|
Fixed Value: preauthorisation/authorization
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common Parameters
|
txid
required
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
||||||||
|
sequencenumber
required
|
Format NUMERIC(1..3)
Permitted values 0..127
Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2 Required for multi partial capture (starting with the 2nd capture) |
||||||||
|
amount
required
|
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99
Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona. The amount must be less than or equal to the amount of the corresponding booking. |
||||||||
|
currency
required
|
Fixed Value EUR
|
||||||||
|
settleaccount
required
|
Format LIST
Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund. |
Article Parameters
|
it[n]
required
|
Format LIST
Parameter it[n] specifies the item type of a shopping cart item. |
||||||||||
|
id[n]
required
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/
International Article Number (EAN bzw. GTIN) Product number, SKU, etc. of this item |
||||||||||
|
pr[n]
required
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||||||
|
no[n]
required
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||||||
|
de[n]
required
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer. |
||||||||||
|
va[n]
optional
|
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]Permitted
VAT rate (% or bp) value < 100 = percent value > 99 = basis points (e.g. 1900 = 19%) |
Response Parameters
|
status
required
|
Permitted Values
APPROVED
ERROR
|
Response Parameter (approved)
|
txid
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
||||||
|
settleaccount
|
Format LIST
Provides information about whether a settlement of balances has been carried out. |
Response Parameter (error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
Format CHAR(1..1024)
The customermessage is returned to your system in order to be displayed to the customer. (Language selection is based on the end customer's language, parameter "language") |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
POST Request genericpayment – add_paydata[action] = profile
Returns the current profile settings for a given Ratepay shop_id.
Account Parameters
|
request
required
|
Fixed Value: genericpayment
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common Parameters
|
clearingtype
required
|
Fixed Value fnc
|
|
financingtype
required
|
Fixed Value RPV, RPD, RPS
RPV: Ratepay Open Invoice RPD: Ratepay Direct Debit RPS: Ratepay Installments |
|
currency
required
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP |
add_paydata PARAMETERS
|
add_paydata[action]
required
|
Fixed Value profile
|
|
add_paydata[shop_id]
required
|
Ratepay Shop ID for current transaction type |
Response Parameter
|
status
required
|
Permitted Values
OK
ERROR
|
Response Parameter (OK)
|
add_paydata[profile-id]
|
ID of the profile at Ratepay |
|
add_paydata[merchant-name]
|
Merchant name at Ratepay |
|
add_paydata[shop-name]
|
Shop name at Ratepay |
|
add_paydata[merchant-status]
|
Status of the merchant 1: not active 2: active |
|
add_paydata[activation-status-invoice]
|
1: not yet or not anymore active 2: active |
|
add_paydata[activation-status-installment]
|
Refer to activation status invoice |
|
add_paydata[activation-status-elv]
|
Refer to activation status invoice |
|
add_paydata[activation-status-prepayment]
|
Refer to activation status invoice |
|
add_paydata[eligibility-ratepay-invoice]
|
Invoice available yes/no |
|
add_paydata[eligibility-ratepay-installment]
|
Installment available yes/no |
|
add_paydata[eligibility-ratepay-elv]
|
ELV available yes/no |
|
add_paydata[eligibility-ratepay-prepayment]
|
Prepayment available yes/no |
|
add_paydata[eligibility-ratepay-pq-light]
|
IBS light available yes/no |
|
add_paydata[eligibility-ratepay-pq-full]
|
IBS full available yes/no |
|
add_paydata[tx-limit-invoice-min]
|
Minimum transaction amount for invoice |
|
add_paydata[tx-limit-invoice-max]
|
Maximum transaction amount for invoice |
|
add_paydata[tx-limit-installment-min]
|
Minimum transaction amount for installment |
|
add_paydata[tx-limit-installment-max]
|
Maximum transaction amount for installment |
|
add_paydata[tx-limit-elv-min]
|
Minimum transaction amount for elv |
|
add_paydata[tx-limit-elv-max]
|
Maximum transaction amount for elv |
|
add_paydata[tx-limit-prepayment-min]
|
Minimum transaction amount for prepayment |
|
add_paydata[tx-limit-prepayment-max]
|
Maximum transaction amount for prepayment |
|
add_paydata[b2b-invoice]
|
B2B Invoice available yes/no |
|
add_paydata[delivery-address-invoice]
|
shipping/billing addresses can differ for invoice yes/no |
|
add_paydata[b2b-installment]
|
B2B installment available yes/no |
|
add_paydata[delivery-address-installment]
|
shipping/billing addresses can differ for invoice yes/no |
|
add_paydata[b2b-elv]
|
B2B ELV available yes/no |
|
add_paydata[delivery-address-elv]
|
shipping/billing addresses can differ for ELV yes/no |
|
add_paydata[b2b-prepayment]
|
B2B Prepayment available yes/no |
|
add_paydata[delivery-address-prepayment]
|
shipping/billing addresses can differ for Prepayment yes/no |
|
add_paydata[b2b-PQ-light]
|
IBS light available for B2B yes/no |
|
add_paydata[delivery-address-PQ-light]
|
shipping/billing addresses can differ for IBS light yes/no |
|
add_paydata[b2b-PQ-full]
|
IBS full available for B2B yes/no |
|
add_paydata[delivery-address-PQ-full]
|
shipping/billing addresses can differ for IBS full yes/no |
|
add_paydata[eligibility-device-fingerprint]
|
Device fingerprinting available yes/no |
|
add_paydata[device-fingerprint-snippet-id]
|
Device fingerprint snippet ID e.g.: yes/no |
|
add_paydata[country-code-billing]
|
Eligible billing countries e.g.: DE, AT, CH |
|
add_paydata[country-code-delivery]
|
Eligible delivery countries e.g.: DE, AT, CH |
|
add_paydata[currency]
|
Eligible billing currencies e.g.: EUR, CHF |
|
add_paydata[interestrate-min]
|
Minimal interest rate p.a. |
|
add_paydata[interestrate-default]
|
Default interest rate p.a. |
|
add_paydata[interestrate-max]
|
Max interest rate p.a. |
|
add_paydata[interest-rate-merchant-towards-bank]
|
Interest rate towards bank |
|
add_paydata[month-number-min]
|
Minimal credit term (months) |
|
add_paydata[month-number-max]
|
Max credit term (months) |
|
add_paydata[month-longrun]
|
Duration of long term payment plans |
|
add_paydata[amount-min-longrun]
|
Minimum transaction amount for long term payment plans |
|
add_paydata[month-allowed]
|
Eligible payment term (months) e.g.: 3, 6, 9, 12, 24 |
|
add_paydata[valid-payment-firstdays]
|
Due day for first payment |
|
add_paydata[payment-firstday]
|
Due day for first payment |
|
add_paydata[payment-amount]
|
Minimum transaction amount |
|
add_paydata[payment-lastrate]
|
Amount of the last rate |
|
add_paydata[rate-min-normal]
|
Minimum rate |
|
add_paydata[rate-min-longrun]
|
Minimum rate for long therm payment plans |
|
add_paydata[service-charge]
|
Service charge |
|
add_paydata[min-difference-dueday]
|
Due day for first payment |
Response Parameter (error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
Format CHAR(1..1024)
The customermessage is returned to your system in order to be displayed to the customer. (Language selection is based on the end customer's language, parameter "language") |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
PAYLOAD
add_paydata[action]=profile
add_paydata[shop_id]=88880103
aid=52078
api_version=3.10
clearingtype=fnc
currency=EUR
encoding=UTF-8
financingtype=RPV
key=19539eb4b369b29f314b51368076475a
mid=14648
mode=test
portalid=2037267
request=genericpayment
RESPONSE
status=OK
add_paydata[eligibility-ratepay-invoice]=yes
add_paydata[delivery-address-invoice]=yes
add_paydata[tx-limit-installment-min]=60
add_paydata[min-difference-dueday]=2
add_paydata[type]=DEFAULT
add_paydata[valid-payment-firstdays]=2
add_paydata[interestrate-default]=13.7
add_paydata[payment-lastrate]=0
add_paydata[eligibility-ratepay-elv]=yes
add_paydata[month-number-max]=48
add_paydata[tx-limit-installment-max]=99999
add_paydata[interestrate-max]=13.7
add_paydata[b2b-prepayment]=yes
add_paydata[delivery-address-prepayment]=yes
add_paydata[payment-firstday]=2
add_paydata[tx-limit-prepayment-max]=99999
add_paydata[country-code-billing]=DE
add_paydata[b2b-invoice]=yes
add_paydata[rate-min-normal]=20
add_paydata[interestrate-min]=13.7
add_paydata[eligibility-ratepay-prepayment]=yes
add_paydata[month-allowed]=3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24
add_paydata[name]=PAYONE_TE_DEU
add_paydata[merchant-name]=PAYONE
add_paydata[tx-limit-prepayment-min]=0
add_paydata[activation-status-invoice]=2
add_paydata[country-code-delivery]=DE
add_paydata[tx-limit-elv-min]=0
add_paydata[tx-limit-invoice-min]=0
add_paydata[delivery-address-elv]=yes
add_paydata[month-longrun]=0
add_paydata[interest-rate-merchant-towards-bank]=9.8
add_paydata[delivery-address-PQ-full]=no
add_paydata[amount-min-longrun]=0
add_paydata[service-charge]=0
add_paydata[shop-name]=PAYONE
add_paydata[eligibility-ratepay-pq-full]=yes
add_paydata[currency]=EUR
add_paydata[b2b-elv]=yes
add_paydata[activation-status-installment]=2
add_paydata[payment-amount]=60
add_paydata[b2b-PQ-full]=no
add_paydata[eligibility-ratepay-installment]=yes
add_paydata[activation-status-prepayment]=2
add_paydata[month-number-min]=3
add_paydata[delivery-address-installment]=yes
add_paydata[rate-min-longrun]=0
add_paydata[activation-status-elv]=2
add_paydata[tx-limit-elv-max]=99999
add_paydata[tx-limit-invoice-max]=99999
add_paydata[profile-id]=PAYONE_TE_DEU
add_paydata[merchant-status]=2
add_paydata[b2b-installment]=no
workorderid=WX1A9DKJC4XNQS4K
POST Request genericpayment – add_paydata[action] = calculation
Account Parameters
|
request
required
|
Fixed Value: genericpayment
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common Parameters
|
clearingtype
required
|
Fixed Value fnc
|
|
financingtype
required
|
Fixed Value RPS
RPS: Ratepay Installments |
|
amount
required
|
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99
Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro. The amount must be less than or equal to the amount of the corresponding booking. |
|
currency
required
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP |
add_paydata PARAMETERS
|
add_paydata[action]
required
|
Fixed Value calculation
|
|
add_paydata[shop_id]
required
|
Mandatory for calculation requests, one of: - calculation-by-rate - calculation-by-time |
|
add_paydata[customer_allow_credit_inquiry]
required
|
Flag if customer allows credit inquiry, has to be “yes” |
|
add_paydata[interest_rate]
optional
|
Interest rate to be used to calculate the annual percentage rate. Optional, if empty default interest rate will be used |
|
add_paydata[rate]
optional
|
Rate that the customer wants to pay per month in smallest currency unit (e.g. cents) Mandatory if calculation type is “calculation-by-rate” |
|
add_paydata[month]
optional
|
Duration of the installment plan in months Mandatory if calculation type is “calculation-by-time” |
|
add_paydata[payment_firstday]
optional
|
Calendar day of the first payment. Possible value: 28 |
|
add_paydata[calculation_start]
optional
|
Day of the first installment. Format: YYYY-MM-DD |
Response Parameters
|
status
|
Permitted Values
OK
ERROR
|
Response Parameter (OK)
|
add_paydata[annual-percentage-rate]
|
Interest-rate based on service-charge and interestrate |
|
add_paydata[interest-amount]
|
Total of all monthly paid interests |
|
add_paydata[amount]
|
Price that has to be financed |
|
add_paydata[number-of-rates]
|
Number of months; duration of the installment plan |
|
add_paydata[rate]
|
Monthly rate to be paid by the customer |
|
add_paydata[last-rate]
|
Last monthly rate to be paid by the customer |
|
add_paydata[interest-rate]
|
Interest-rate which will be used to calculate the annual percentage rate |
|
add_paydata[monthly-debit-interest]
|
Monthly interest rates based on annual-percentagerate |
|
add_paydata[service-charge]
|
Additional costs of financing |
|
add_paydata[total-amount]
|
Total of amount, interest-amount and service-charge. Has to be transferred in the Preauthorization in add_paydata[amount]. |
|
add_paydata[payment-firstday]
|
Calendar day of the first payment. Possible value: 28 |
Response Parameter (Error)
Request Body schema: application/json
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
Format CHAR(1..1024)
The customermessage is returned to your system in order to be displayed to the customer. (Language selection is based on the end customer's language, parameter "language") |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
POST Request genericpayment – add_paydata[action] = update
The call needs to provide the new list of items representing the complete shopping cart (don’t send the difference/changes, instead you need to send the complete new item list).
An update is only possible as long as the preauthorization is not captured completely.
The amount can’t be higher as the amount of the preauthorization. A lower amount is allowed.
Account Parameters
|
request
required
|
Fixed Value: genericpayment
|
|
mid
required
|
your merchant ID, 5-digit numeric
|
|
aid
required
|
your subaccount ID, 5-digit numeric
|
|
portalId
required
|
your Portal ID, 7-digit numeric
|
|
key
required
|
your key value, alpha-numeric
|
common parameters
|
clearingtype
required
|
Fixed Value fnc
|
|
financingtype
required
|
Fixed Value RPV
RPV: Ratepay Open Invoice |
|
amount
required
|
Required for action=pre_check and action=calculation |
|
currency
required
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP |
|
country
required
|
Format LIST
Permitted values ISO 3166 2-letter-codes
Samples
DE GB US Specifies country of address for the customer. Some countries require additional information in parameter "state"
|
|
workorderid
required
|
Referencing the reservation |
add_paydata PARAMETERS
|
add_paydata[action]
required
|
Fixed Value update
|
|
add_paydata[reservation_txid]
required
|
Referencing the reservation |
|
add_paydata[shop_id]
required
|
Ratepay Shop ID for current transaction type |
Article Parameters
|
it[n]
required
|
|
||||||||||
|
id[n]
required
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/
International Article Number (EAN bzw. GTIN) Product number, SKU, etc. of this item |
||||||||||
|
pr[n]
required
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||||||
|
no[n]
required
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||||||
|
de[n]
required
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer. |
||||||||||
|
va[n]
optional
|
VAT rate (%)
value < 100 = percent |
Response Parameters
|
status
|
Permitted Values
OK
ERROR
|
Response Parameter (ok)
|
workorderid
|
Format CHAR(1..50)
The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request. |
Response Parameter (Error)
Request Body schema: application/json
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
Format CHAR(1..1024)
The customermessage is returned to your system in order to be displayed to the customer. (Language selection is based on the end customer's language, parameter "language") |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
Sequence Diagrams
Invoice - Preauthorization
|
Invoice - Authorization
|
Invoice and Installment – Refund
|
Installment – Preauthorization
|
Installment – Authorization
|
|
Invoice and Installment - Complete Cancellation
|
Invoice and Installment – Partial Cancellation
|
Invoice and Installment - Multi Partial Capture
|
Appendix
Company types
|
Country |
Legal Form |
Description (German) |
Company-Type |
|---|---|---|---|
|
DE |
GmbH |
Gesellschaft mit beschränkter Haftung |
GMBH |
|
DE |
GmbH i.Gr. |
GmbH in Gründung |
GMBH-I-GR |
|
DE |
gGmbH |
Gemeinnützige GmbH |
GGMBH |
|
DE |
GmbH Co. KG |
Gesellschaft mit beschränkter Haftung Compagnie Kommanditgesellschaft |
GMBH-CO-KG |
|
DE |
OHG |
Offene Handelsgesellschaft |
OHG |
|
DE |
KG |
Kommanditgesellschaft |
KG |
|
DE |
e.V. |
Eingetragener Verein |
EV |
|
DE |
e.G. |
Eingetragene Genossenschaft |
EG |
|
DE |
AG |
Aktiengesellschaft |
AG |
|
DE |
UG |
Unternehmergesellschaft |
UG |
|
DE |
UG i.Gr. |
Unternehmergesellschaft in Gründung |
UG-I-GR |
|
DE |
Einzelunternehmen |
EINZELUNTERNEHMER |
|
|
DE |
e.K. |
Eingetragener Kaufmann |
EK |
|
DE |
Partnerschaft |
PARTNERSCHAFT |
|
|
DE |
GbR |
Gesellschaft bürgerlichen Rechts |
GBR |
|
DE |
Anstalt öffentlichen Rechts |
AOR |
|
|
DE |
Körperschaft öffentlichen Rechts |
KOR |
|
|
DE |
Stiftung |
STIFTUNG |
|
|
DE |
andere |
Sammeltyp für alle anderen Gesellschaftsformen |
OTHER |
|
EU |
SE |
Europäische Gesellschaft |
SE |
|
EU |
SCE |
Europäische Genossenschaft |
SCE |
|
EU |
andere |
Sammeltyp für alle anderen Gesellschaftsformen |
OTHER |
|
AT |
Einzelunternehmen |
EINZELUNTERNEHMER |
|
|
AT |
GmbH |
Gesellschaft mit beschränkter Haftung |
GMBH |
|
AT |
GbR |
Gesellschaft bürgerlichen Rechts |
GBR |
|
AT |
OG |
Offene Gesellschaft |
OG |
|
AT |
OHG |
Offene Handelsgesellschaft |
OHG |
|
AT |
KG |
Kommanditgesellschaft |
KG |
|
AT |
GmbH Co. KG |
Gesellschaft mit beschränkter Haftung |
GMBH-CO-KG |
|
AT |
AG |
Aktiengesellschaft |
AG |
|
AT |
OEG |
Offene Erwerbsgesellschaft |
OEG |
|
AT |
KEG |
Kommanditerwerbsgesellschaft |
KEG |
|
AT |
andere |
Sammeltyp für alle anderen Gesellschaftsformen |
OTHER |
|
CH |
Einzelunternehmen |
CH_EINZELUNTERNEHMER |
|
|
CH |
Einfache Gesellschaft |
EINFACHE-GESELLSCHAFT |
|
|
CH |
Kollektivgesellschaft |
KOLLEKTIVGESELLSCHAFT |
|
|
CH |
Kommanditgesellschaft |
KG |
|
|
CH |
AG |
Aktiengesellschaft |
AG |
|
CH |
GmbH |
Gesellschaft mit beschränkter Haftung |
GMBH |
|
CH |
Andere |
Sammeltyp für alle anderen Gesellschaftsformen |
OTHER |
Tracking provider mapping
|
Tracking provider |
Description |
|---|---|
|
AT |
AG |
|
DPD |
Deutscher Paket Dienst |
|
GLS |
General Logistics Systems |
|
DHL |
Dalsey Hilfbloom Lynn International |
|
HLG |
Hermes Logistics Group |
|
HVS |
Hermes Versand Service |
|
UPS |
United Parcel Service |
|
TNT |
Thonas Nationwide Transport |
|
OTH |
Other (without tracking) |
Testdata
Please refer to the Ratepay documentation for specific test data: https://ratepay.redoc.ly/docs/developer/testing/test_data/
You can test your implementation of our API for Ratepay in test mode using these shop-IDs:
| shop_id | profile-id | currency |
|---|---|---|
|
88880103 |
PAYONE_TE_DEU |
EUR |
|
88880104 |
PAYONE_TE_AUT |
EUR |
|
88880105 |
PAYONE_TE_CH |
CHF |
|
99981936 |
PAYONE_TE_NL |
EUR |