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

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
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]
optional
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%)
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


























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 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]


optional




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










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: 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








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





































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








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: 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




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 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]


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





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