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

---end

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.

---end

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

---end

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.

---end

Article Parameters
it[n]
optional
Format LIST
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount
id[n]
optional
Format CHAR(1..32)
Array 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]
optional
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]

Unit gross price of the item in smallest unit! e.g. cent

no[n]
optional
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
optional
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

---end

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
de[1]=Product 1 de[2]=Product 2 de[3]=Product 3 de[400]=Product 400
RESPONSE
status=APPROVED
txid=123456789
userid=987654321
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

---end

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.

---end

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

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

---end

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 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 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 Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
required
Format NUMERIC(4)
Array 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%)

---end

Response Parameters
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
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)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

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
    
Edit your payload here
    key1=value1
    key2=value2
    key3=value3
    ...
    
Edit your response here
    key1=value1
    key2=value2
    key3=value3
    ...
    

---end

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

---end

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.

---end

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 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 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 Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
required
Format NUMERIC(4)
Array 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%)

---end

---end

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
    
Edit your payload here
    key1=value1
    key2=value2
    key3=value3
    ...
    
Edit your response here
    key1=value1
    key2=value2
    key3=value3
    ...
    

---end

POST Request genericpayment – add_paydata[action] = profile

Returns the current profile settings for a given Ratepay shop_id.

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

---end

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

---end

add_paydata PARAMETERS
add_paydata[action]
required
Fixed Value profile
add_paydata[shop_id]
required
Ratepay Shop ID for current transaction type

---end

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
Edit your payload here
key1=value1
key2=value2
key3=value3
...
Edit your response here
key1=value1
key2=value2
key3=value3
...
POST Request genericpayment – add_paydata[action] = calculation
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

---end

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

---end

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

---end

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
Edit your payload here
key1=value1
key2=value2
key3=value3
...
Edit your response here
key1=value1
key2=value2
key3=value3
...
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: 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

---end

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

---end

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

---end

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 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 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 Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
required
VAT rate (%)

value < 100 = percent

---end

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

---end

Host: api.pay1.de
    Content-Type: application/x-www-form-urlencoded
    
Edit your payload here
    key1=value1
    key2=value2
    key3=value3
    ...
    
Edit your response here
    key1=value1
    key2=value2
    key3=value3
    ...
    

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

GMBH

DE

GmbH i.Gr.

GmbH in Gründung

GMBH-I-GR

DE

gGmbH

Gemeinnützige GmbH

GGMBH

DE

GmbH & Co. KG

GMBH-CO-KG

DE

OHG

OHG

DE

KG

KG

DE

e.V.

Eingetragener Verein

EV

DE

e.G.

Eingetragene Genossenschaft

EG

DE

AG

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

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

GMBH

AT

GbR

GBR

AT

OG

Offene Gesellschaft

OG

AT

OHG

OHG

AT

KG

KG

AT

GmbH & Co. KG

GMBH-CO-KG

AT

AG

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

AG

CH

GmbH

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

88880133

PAYONE_TE_NL

EUR