Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Ratepay specific requests

UI Text Box
typeinfo
  • genericPayment(calculation) is used for the calculation of installment plans
  • genericPayment(profile) is used for retrieval of account settings from Ratepay

Preauthorization/Authorization

UI Text Box
typeinfo

Additional parameters for use with "preauthorization" or “authorization”.

Request

Parameter

Required

Comment

clearingtype

+

Has to be "fnc": Financing

add_paydata[shop_id]

+

Shop ID for the relevant Ratepay Channel. You will receive the shop_ids from Ratepay

financingtype

+

RPV: Ratepay Open Invoice

RPD: Ratepay Direct Debit

RPS: Ratepay Installments

amount

+

Total amount (in smallest currency unit! e.g. cent)

For RPS: Only the sum of all articles without the payment plan service charges

add_paydata[customer_allow_credit_inquiry]

+

Legacy field, please always pass "yes"

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

add_paydata[device_token]

-

Token associating the gathered

customer’s device-data with the

current transaction

add_paydata[debit_paytype]

o

Mandatory for financingtype=RPS, one of:

-          DIRECT-DEBIT

-          BANK-TRANSFER


company

o

Company name – if company name is set the transaction is considered B2B

add_paydata[vat_id]

-

Sending this information can increase the acceptance rate.

Company VAT ID

add_paydata[company_id]

-

Sending this information can increase the acceptance rate.

The customer’s company-ID (German “Handelsregisternummer”)

add_paydata[registry_location]

o

Mandatory if transaction is B2B

City of the company’s register court

add_paydata[company_type]

o

Mandatory if transaction is B2B

Refer to appendix 3.1. “company types” for values

add_paydata[homepage]

o

Mandatory if transaction is B2B

add_paydata[registry_country_code]

o

Mandatory if registry address is provided

Country code ISO-3166 alpha 2

add_paydata[registry_city]

o

Mandatory if registry address is provided

Company registry city

add_paydata[registry_zip]

o

Mandatory if registry address is provided, includes number

Company registry ZIP

add_paydata[registry_street]

o

Mandatory if registry address is provided

Company registry street

add_paydata[installment_amount]

o

General amount the customer has to pay each month in smallest currency unit (e.g. cents)

Required for RPS

add_paydata[installment_number]

o

Number of months for which the customer must pay the installment-amount

Required for RPS

add_paydata[last_installment_amount]

o

Amount of the last installment bank transfer in smallest currency unit (e.g. cents)

Required for RPS

add_paydata[interest_rate]

o

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]

o

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]


narrative_text

-

Dynamic text element on account statements

reference

+

Merchant reference number for the payment process

email

+

Customers e-mail address

birthday

+

Date of birth (YYYYMMDD)

telephonenumber

+

Telephone number

it[n]

+

Excerpt Include
it[n] - definition
it[n] - definition
nopaneltrue

id[n]

+

International Article Number (EAN bzw. GTIN)

Excerpt Include
id[n] - definition
id[n] - definition
nopaneltrue

pr[n]

+

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

no[n]

+

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

de[n]

+

Excerpt Include
de[n] - definition
de[n] - definition
nopaneltrue

iban

o

International Bank Account Number

Mandatory for RPD and RPS with add_paydata[debit_paytype]=DIRECT-DEBIT

Excerpt Include
iban - definition
iban - definition
nopaneltrue

bic

o

Bank Identifier Code

Mandatory for RPD and RPS with add_paydata[debit_paytype]=DIRECT-DEBIT

Excerpt Include
bic - definition
bic - definition
nopaneltrue

firstname

+

First name

lastname

+

Surname

street

+

Street number and name

zip

+

Postcode

city

+

City

country

+

Excerpt Include
country - definition
country - definition
nopaneltrue

add_paydata[referenceid]-

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

Consumer identifier for internal ratepay use.

AN..100

Response

Parameter

Required

Comment

status

+

APPROVED

txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

userid

+

Excerpt Include
userid - definition
userid - definition
nopaneltrue

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice

Parameter (ERROR)

errorcode

+

Error number

Excerpt Include
errorcode - definition
errorcode - definition
nopaneltrue

errormessage

-

Error message

Excerpt Include
errormessage - definition
errormessage - definition
nopaneltrue

customermessage

-

Excerpt Include
customermessage - definition
customermessage - definition
nopaneltrue


Capture

Request

Parameter

Required

Comment

txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

capturemode

+

Excerpt Include
capturemode - definition
capturemode - definition
nopaneltrue

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

The amount must be less than or equal to the amount of the corresponding booking.

sequencenumber

o

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)

it[n]

+

Excerpt Include
it[n] - definition
it[n] - definition
nopaneltrue

id[n]

+

Excerpt Include
id[n] - definition
id[n] - definition
nopaneltrue

pr[n]

+

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

no[n]

+

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

de[n]

+

Excerpt Include
de[n] - definition
de[n] - definition
nopaneltrue

va[n]

+

VAT rate (% or bp)

value < 100 = percent

value > 99 = basis points (e.g. 1900 = 19%)

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

add_paydata[shop_id]

+

Ratepay Shop ID for current transaction type

add_paydata[tracking_provider_[n]]

o

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

o

Tracking ID of delivery item

“tracking_provider” and “tracking_id” must be provided for same [n]

narrative_text

-

Human readable description of the reason for the transaction

add_paydata[referenceid]-

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

Consumer identifier for internal ratepay use.

AN..100

 Response

Parameter

Required

Comment

status

+

APPROVED / ERROR

txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice

Parameter (APPROVED)



txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

Parameter (ERROR)



errorcode

+

Error number

Excerpt Include
errorcode - definition
errorcode - definition
nopaneltrue

errormessage

+

Error message

Excerpt Include
errormessage - definition
errormessage - definition
nopaneltrue

Debit/Refund

UI Text Box
typetip

Refund with Ratepay can currently only be ordered via this API, not via the PMI.

Request

Parameter

Required

Comment

txid                

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

sequencenumber

o

Excerpt Include
sequencenumber - definition
sequencenumber - definition
nopaneltrue

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

The amount must be less than or equal to the amount of the corresponding booking.

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

it[n]

-

Excerpt Include
it[n] - definition
it[n] - definition
nopaneltrue

id[n]

-

Excerpt Include
id[n] - definition
id[n] - definition
nopaneltrue

pr[n]

-

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

no[n]

-

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

de[n]

-

Description (on invoice)

va[n]

-

Excerpt Include
va[n] - definition
va[n] - definition
nopaneltrue

settleaccount

+

Excerpt Include
settleaccount - definition
settleaccount - definition
nopaneltrue

add_paydata[shop_id]

+

Shop ID for the relevant Ratepay Channel

add_paydata[referenceid]-

Can be used to submit additional merchant reference to ratepay. This field will be sent to ratepay as <reference-id>. This data will not be stored. If you use settleaccount=no, we will not transmit this data to ratepay.

AN..255
add_paydata[merchant_consumer_id]-

Consumer identifier for internal ratepay use.

AN..100

genericPayment - add_paydata[action] = profile

UI Text Box
typeinfo

Returns the current profile settings for a given Ratepay shop_id.

Request

Parameter

Required

Comment

add_paydata[action]

+

Has to be „profile“

add_paydata[shop_id]

+

Ratepay Shop ID for current transaction type

clearingtype

+

Has to be "fnc": Financing

financingtype

+

RPV: Ratepay-Invoicing

RPS: Ratepay-Installment

RPD: Ratepay-Debit

RPP: Ratepay-Prepayment

currency+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

 Response

Parameter

Required

Comment

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

 genericPament- add_paydata[action] = calculation

Request

Parameter

Required

Comment

add_paydata[action]

+

Has to be „calculation“

clearingtype

+

Has to be "fnc": Financing

financingtype

+

RPS: Ratepay-Installment

amount

+

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

add_paydata[shop_id]

+

Ratepay Shop ID for current transaction type

add_paydata[calculation_type]

+

Mandatory for calculation requests, one of:

-   calculation-by-rate

-   calculation-by-time

add_paydata[customer_allow_credit_inquiry]

+

Flag if customer allows credit inquiry, has to be “yes”

add_paydata[interest_rate]

-

Interest rate to be used to calculate the annual percentage rate.

Optional, if empty default interest rate will be used

add_paydata[rate]

o

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]

o

Duration of the installment plan in months

Mandatory if calculation type is “calculation-by-time”

add_paydata[payment_firstday]

-

Calendar day of the first payment. Possible value: 28

add_paydata[calculation_start]

-

Day of the first installment.

Format: YYYY-MM-DD

 Response

Parameter

Required

Comment

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

genericPament- add_paydata[action] = update

UI Text Box
typeinfo

To update an order, you need to send a genericpayment-request with 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.

Request 

Parameter

Required

Comment

add_paydata[action]

+

Request action. This has to be „update“

add_paydata[reservation_txid]

+

Referencing the reservation

add_paydata[shop_id]

+

Ratepay Shop ID for current transaction type

workorderid

+

Referencing the reservation

country

+

Excerpt Include
country - definition
country - definition
nopaneltrue

amount

+

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

financingtype

+

RPV – Ratepay-Invoicing

it[n]

+

Excerpt Include
it[n] - definition
it[n] - definition
nopaneltrue

id[n]

+

International Article Number (EAN bzw. GTIN)

pr[n]

+

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

no[n]

+

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

de[n]

+

Item Description (on invoice)

va[n]

+

VAT rate (%)

value < 100 = percent

 Example request to update the shopping cart items

Code Block
add_paydata[action]=update
add_paydata[reservation_txid]=TX1A174RES51X0FR
add_paydata[shop_id]=88880103
aid=27989
amount=2340
api_version=3.10
clearingtype=fnc
country=DE
currency=EUR
de[1]=the socks for the bold an the beautiful
encoding=UTF-8
financingtype=RPV
id[1]=socks1
integrator_name=tk
integrator_version=0.2
it[1]=goods
key=bc56727726a6cef915649bc0b32d7ba8
mid=14648
mode=test
no[1]=1
portalid=2022129
pr[1]=2340
request=genericpayment
solution_name=SDK
solution_version=0.2
va[1]=1900
workorderid=WX1A174RESGHVDQ2

Example Response

Code Block
status=OK
workorderid=WX1A174RESGHVDQ2

Sequence Diagrams

Invoice - Preauthorization

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision4
diagramNameRatepay_Invoice_preauthorization
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice - Authorization

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision5
diagramNameRatepay_invoice_authorization
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Installment – Preauthorization

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision6
diagramNameRatepay_Installment_Preauthorization
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Installment – Authorization

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision5
diagramNameratepay_installment_authorization
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice and Installment - Complete Cancellation

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision5
diagramNameratepay_invoice_installment_cpmplete_cancellation
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice and Installment - Multi Partial Capture

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision6
diagramNameratepay_invoice_installment_multi_patial_capture
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice and Installment – Partial Cancellation

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision7
diagramNameratepay_invoice_installment_partial_cancellation
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice and Installment – Refund

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision9
diagramNameratepay_invoice_installment_refund
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

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)


Table of Contents
outlinetrue
indent2em