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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount
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
Value Comment
completed Set with last capture; i.e.: Delivery completed.No further capture is allowed.
notcompleted Set with partial deliveries (last delivery with "completed") Another capture is expected to complete the transaction.

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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

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
Value Comment
yes Settlement of outstanding balances is carried out.
no Do not carry out settlement of outstanding balances, book request only.
auto The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

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
Value Comment
yes Settlement of outstanding balances has been carried out.
no Settlement of outstanding balances has not been carried out.

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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount
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
Compagnie Kommanditgesellschaft

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