Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Ratepay specific requests
| UI Text Box | ||
|---|---|---|
| ||
|
Preauthorization/Authorization
| UI Text Box | ||
|---|---|---|
| ||
Additional parameters for use with "preauthorization" or “authorization”. |
Request
Parameter | Required | Comment | ||||||||
+ | Has to be "fnc": Financing | |||||||||
add_paydata[shop_id] | + | Shop ID for the relevant Ratepay Channel | ||||||||
+ | RPV: Ratepay-Invoicing RPS: Ratepay-Installment RPD: Ratepay-Debit | |||||||||
+ | 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] | + | Flag that displays, whether or not the customer allows a credit inquiry - has to be “yes”, defaults to “no” | ||||||||
+ |
| |||||||||
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
| ||||||||
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] | ||||||||
- | Dynamic text element on account statements | |||||||||
+ | Merchant reference number for the payment process | |||||||||
+ | Customers e-mail address | |||||||||
+ | Date of birth (YYYYMMDD) | |||||||||
+ | Telephone number Mandatory for payment type KLV, KLS | |||||||||
+ |
| |||||||||
+ | International Article Number (EAN bzw. GTIN)
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
o | International Bank Account Number Mandatory for RPD and RPS with add_paydata[debit_paytype]=DIRECT-DEBIT
| |||||||||
o | Bank Identifier Code Mandatory for RPD and RPS with add_paydata[debit_paytype]=DIRECT-DEBIT
| |||||||||
+ | First name | |||||||||
+ | Surname | |||||||||
+ | Street number and name | |||||||||
+ | Postcode | |||||||||
+ | City | |||||||||
+ |
| |||||||||
| 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 | |||||||||
+ |
| ||||||||||
+ |
| ||||||||||
add_paydata[clearing_reference] | + | accounting number, used to print on the invoice | |||||||||
Parameter (ERROR) | |||||||||||
+ | Error number
| ||||||||||
- | Error message
| ||||||||||
- |
| ||||||||||
Capture
Request
Parameter | Required | Comment | ||||||||
+ |
| |||||||||
+ |
| |||||||||
+ | 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. | |||||||||
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) | |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ | VAT rate (% or bp) value < 100 = percent value > 99 = basis points (e.g. 1900 = 19%) | |||||||||
+ |
| |||||||||
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] | ||||||||
- | 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 | ||||||||
+ |
| |||||||||
add_paydata[clearing_reference] | + | accounting number, used to print on the invoice | ||||||||
Parameter (APPROVED) |
|
| ||||||||
+ |
| |||||||||
Parameter (ERROR) |
| |||||||||
+ | Error number
| |||||||||
+ | Error message
|
Debit/Refund
| UI Text Box | ||
|---|---|---|
| ||
Refund with Ratepay can currently only be ordered via this API, not via the PMI. |
Request
Parameter | Required | Comment | ||||||||
+ |
| |||||||||
o |
| |||||||||
+ | 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. | |||||||||
+ |
| |||||||||
- |
| |||||||||
- |
| |||||||||
- |
| |||||||||
- |
| |||||||||
- | Description (on invoice) | |||||||||
- |
| |||||||||
+ |
| |||||||||
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 | ||
|---|---|---|
| ||
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 | |
+ | Has to be "fnc": Financing | ||
+ | RPV: Ratepay-Invoicing RPS: Ratepay-Installment RPD: Ratepay-Debit RPP: Ratepay-Prepayment | ||
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“ | ||||||||
+ | Has to be "fnc": Financing | |||||||||
+ | RPS: Ratepay-Installment | |||||||||
+ |
| |||||||||
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 | ||
|---|---|---|
| ||
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 | ||||||||
+ | Referencing the reservation | |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ | RPV – Ratepay-Invoicing | |||||||||
+ |
| |||||||||
+ | International Article Number (EAN bzw. GTIN) | |||||||||
+ |
| |||||||||
+ |
| |||||||||
+ | Item Description (on invoice) | |||||||||
+ | 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 | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Invoice - Authorization
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Installment – Preauthorization
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Installment – Authorization
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Invoice and Installment - Complete Cancellation
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Invoice and Installment - Multi Partial Capture
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Invoice and Installment – Partial Cancellation
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Invoice and Installment – Refund
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 | ||||
|---|---|---|---|---|
|