About Ratepay

General information about Ratepay

With payment by invoice you can reduce the number of uncompleted orders in your online shop by up to 81%. This increases your turnover and your sales. Therefore allows purchase on account in several European countries with payment guarantee. Rate payment at the online shop motivates your customers to order high value baskets. This also increases your turnover. Therefore offers guaranteed hire purchase within several European countries.

With Ratepay you profit as a merchant from a full invoice and hire purchase service. Therefore you pass on all the invoice data during the order to the service provider. That than takes over the complete billing and debtor management. As merchant you get a payment guarantee. Furthermore Ratepay offers classical hire purchase and SEPA direct debit.

Ratepay guarantees an online consent in seconds for purchases by instalment during the order process. A PostIdent-process is not necessary. Ratepay transfers the invoice amount rapidly to the merchant and bears the non-payment risk themselves.

Logo

Info

Ratepay offers payments solutions for purchases on invoice and hire purchases as well as direct debits with full processing and carries to complete risk of payments defaults.

Type

Payments by Invoice and Installments

Further information can be found on the webpage of Ratepay (http://www.ratepay.com).

Process flow chart

Ratepay process flow

interface

Ratepay invoice and hire purchase

A payment with Ratepay consists of several transaction steps. At the start an initialisation is necessary, which returns the permissible methods of payment for the customer: purchase on invoice, hire purchase or direct debit. If the customer wants hire purchase the instalment calculator must be displayed. The payment is subsequently created, confirmed, changed if needed and finally captured. Credits are also possible.

Ratepay has 5 different requests which must be carried out in the payment process depending on the situation and progress. converts these requests into the corresponding Ratepay requests. In this case the following mapping applies:

request	Ratepay request	Description	Beschreibung
INIT / Authorize	PAYMENT_INIT (PAYMENT_QUERY)	executes automatically the request PAYMENT_INIT. If a merchant uses Integrated Payment Control (IBS) the PAYMENT_QUERY request is carried out. EventToken = A	führt automatisiert den Request PAYMENT_INIT durch. Wenn ein Händler die integrierte Bezahlsteuerung (IBS) nutzt, wird der Request PAYMENT_QUERY ausgeführt. EventToken = A
Create payment (Authorize step 1)	PAYMENT_REQUEST	Initialises a purchase by instalment or purchase on account EventToken = R	Initialisiert einen Raten- bzw. Rechnungskauf EventToken = R
Verify (Authorize step 2)	PAYMENT_CONFIRM	Confirms the initialisation again. can also automate this request. Please leave this request out in that case (contact our support for this). EventToken = V	Bestätigt die Initialisierung erneut. kann diesen Request auch automatisieren. Dann lassen sie diesen Request bitte aus (Wenden sie sich hierfür an unseren Support). EventToken = V
Order change (before capture)	PAYMENT_CHANGE	Optional: Here the payment can be modified. Possible are: - Full cancellation / EventToken = FC - Partial cancellation / EventToken = PC - Order change / EventToken = CO	Optional: Hiermit kann die Zahlung bearbeitet werden. Möglich sind: - Vollstornierung / EventToken = FC - Teilstornierung / EventToken = PC - Auftragsänderung / EventToken = CO
Capture	CONFIRMATION_DELIVERY	Activates and/or carries out payment. This request must be given when the goods are shipped for reasons of liability and falling due! EventToken = C	Aktiviert bzw. führt die Zahlung durch. Aus Haftungs- und Fälligkeitsgründen muss dieser Request beim Versand der Ware erfolgen! EventToken = C
Order change (after capture)	PAYMENT_CHANGE	Optional: Here the payment can be modified. Possible are: - Full return / EventToken = FC - Partial return / EventToken = PR - Credit / EventToken = CR	Optional: Hiermit kann die Zahlung bearbeitet werden. Möglich sind: - Vollrückgabe / EventToken = FR - Teilrückgabe / EventToken = PR - Gutschrift / EventToken = CR

Initialising Ratepay payments

In order to initialise a Ratepay payment via server-to-server communication, please use the following URL:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
OrderDesc	ans..768	O	Description of the goods purchased	Beschreibung der gekauften Waren
E-mail	ans..255	M	eMail address of the card holder	E-Mail-Adresse des Karteninhabers
CustomerID	an..30	O	Unique customer ID in merchant system or the customer’s email address	Eindeutige ID des Kunden im Händlersystem oder die E-Mail-Adresse des Kunden
CustomerClassification	ans..8	O	Instruction to risk management about type of customer: negative, neutral, positive, vip	Anweisung an das Risikomanagement, um welchen Kundentyp es sich handelt: negative, neutral, positive, vip
Title	ans..45	O	Title	Titel
Salutation	ans..45	O	Salutation	Anrede
Gender	a1	M	Gender: Sex (M=male / F=female / U=unknown)	Geschlecht: M=male, F=female, U=unknown
DateOfBirth	dttm8	C	Date of birth in the format YYYYMMDD. Optional for B2B (CompanyName transmitted), otherwise mandatory.	Geburtsdatum im Format JJJJMMTT. Optional bei B2B (CompanyName angegeben), sonst Pflicht.
PhoneAreaCode	ans..30	C	Telephone code. Mandatory if MobileAreaCode is not transmitted.	Telefonvorwahl. Pflicht, wenn kein MobileAreaCode übergeben ist.
Phone	ans..30	C	Phone number. Mandatory if Mobile is not transmitted.	Rufnummer. Pflicht, wenn kein Mobile übergeben ist.
FaxAreaCode	ans..30	O	Fax area code	Fax-Vorwahl
Fax	ans..30	O	Fax number	Faxnummer
MobileAreaCode	ans..30	C	Mobile area code. Mandatory if PhoneAreaCode is not transmitted.	Mobil-Vorwahl. Pflicht, wenn kein PhoneAreaCode übergeben ist.
Mobile	ans..30	C	Mobile telephone number. Mandatory if Phone is not transmitted.	Mobiltelefonnummer. Pflicht, wenn kein Phone übergeben ist.
AccOwner	ans..55	C	Name of account holder. Mandatory for direct debit.	Name des Kontoinhabers. Pflicht bei DirectDebit.
IBAN	ans..34	C	International Bank Account Number. Mandatory for direct debit.	International Bank Account Number. Pflicht bei DirectDebit.
BIC	ans11	O	Bank Identifier Code	Bank Identifier Code
AccBank	ans..27	O	Name of the financial institution	Name des Kreditinstituts
Nationality	a2	M	Country code of customer's country of origin according to ISO-3166 alpha 2	Ländercode des Herkunftslandes des Kunden gemäß ISO-3166 alpha 2
AllowCredInq	a..3	M	Customer agrees to the passing on of his details for credit offers (yes/no)	Kunde stimmt der Weitergabe seiner Daten für Kreditangebote zu (yes/no)
ShopSystem	ans..127	O	Name of the shop system	Name des Shop-Systems
ShopSystemVersion	ans..127	O	Version name of the shop system	Versionsname des Shop-Systems
ShoppingBasket	ans..1024	M	Current shopping basket (for structure see table Shopping-Basket)	Aktueller Warenkorb (Aufbau siehe Tabelle Shopping-Basket)
ShoppingBasketAmount	n..10	M	Total value of shopping basket in smallest currency unit (less discount, incl. shipment etc.)	Gesamtwert des Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.)
Discount	ans..100	O	Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900	Warenkorbübergreifender Rabatt. Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Rabatt;1000;1900
ShippingProfile	ans..100	O	Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900	Versandkosten Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Versand;500;1900
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
EventToken	a..2	M	„A“ for authorization	„A“ für Autorisierung
			Company data (B2B)	Firmendaten (B2B)
CompanyName	ans..100	C	Company name, obligatory for B2B	Firmenname, Pflicht bei B2B
VatID	ans..25	C	VAT-ID, obligatory for B2B	Umsatzsteuer-ID, Pflicht bei B2B
CompanyID	ans..50	O	Register of Companies number	Handelsregisternummer
LegalForm	ans..100	O	Legal form. The value to be transmitted must be coordinated with Ratepay!	Rechtsform. Zu übergebender Wert muss mit Ratepay abgestimmt werden!
RegistryLocation	ans..255	O	Company's principal office	Firmensitz
Homepage	ans..255	O	Homepage of the company	Homepage des Unternehmens
			Delivery data	Lieferdaten
sdFirstName	ans..100	O	First name of the customer	Vorname des Kunden
sdLastName	ans..100	O	Last name of the customer	Nachname des Kunden
sdStreet	ans..100	O	Street name and house number	Straßenname und Hausnummer
sdStreetHouseNumber	ans..10	O	Street number	Hausnummer
sdStreetAddition	ans..50	O	Addition in the delivery address	Zusatz in der Lieferadresse
sdZIPCode	ans..10	O	Postcode	Postleitzahl
sdCity	ans..255	O	City	Ort
sdCountryCode	a2	O	Two characters country code according to ISO 3166	Ländercode zweistellig gemäß ISO 3166
sdPhone	ns..32	O	Customer’s phone number	Telefonnummer des Kunden
			Invoice data (check address)	Rechnungsdaten (Prüfadresse)
bdFirstName	ans..100	M	First name of the custumer	Vorname des Kunden
bdLastName	ans..100	M	Last name of the customer	Nachname des Kunden
bdCompanyName	ans..100	O	Name of company	Firmenname
bdStreet	ans..50	M	Street name in the invoicing address	Straßenname der Rechnungsadresse
bdStreetNr	ans..10	M	Street number of the invoicing address	Hausnummer der Rechnungsadresse
bdStreetAddition	ans..50	O	Address addition in the billing address	Adresszusatz der Rechnungsadresse
bdZIP	ans..10	M	Postcode in the invoicing address	Postleitzahl der Rechnungsadresse
bdCity	ans..255	M	Town/city of the invoicing address	Ort der Rechnungsadresse
bdCountryCode	a2	M	Country code for the invoicing address, 2 characters according to ISO 3166	Ländercode der Rechnungsadresse zweistellig gemäß ISO 3166
bdPhone	ns..32	M	Customer’s phone number	Telefonnummer des Kunden
			Registration address (B2B)	Registrierungsadresse (B2B)
FirstName	ans..100	O	First name	Vorname
LastName	ans..100	O	Last name	Nachname
AddrStreet	ans..50	C	Street. Mandatory if B2B (CompanyName is given).	Straße. Pflicht wenn B2B (CompanyName angegeben).
AddrStreetNr	ans..10	C	Street number. Mandatory if B2B (CompanyName is given)	Hausnummer. Pflicht wenn B2B (CompanyName angegeben).
AddressAddition	ans..50	O	Address c/o	Adresszusatz
AddrZip	ans..10	C	Postcode. Mandatory if B2B (CompanyName is given).	Postleitzahl. Pflicht wenn B2B (CompanyName angegeben).
AddrCity	ans..32	C	City. Mandatory if B2B (CompanyName is given).	Ort. Pflicht wenn B2B (CompanyName angegeben).
AddrCountryCode	a2	C	Two characters country code according to ISO 3166. Mandatory if B2B (CompanyName is given).	Ländercode zweistellig gemäß ISO 3166. Pflicht wenn B2B (CompanyName angegeben).
			Fraud prevention	Betrugsprävention
IPAddr	ans..15	M	With the transferred IP address can determine in which country and in which town your customer has connected with the Internet (see also IPZone). Format: 123,456,789,012	Durch die übergebene IP-Adresse kann das ermitteln, in welchem Land und in welcher Stadt Ihr Kunde mit dem Internet verbunden ist (vgl. IPZone). Format: 123.456.789.012
DeviceToken	ans..100	O	Device token, see external documentation from Ratepay	Geräte-Token, siehe externe Dokumentation von Ratepay

Parameters for Ratepay payments

Key	Format	CND	Description	Beschreibung
Status	a..50	M	INIT or FAILED	INIT oder FAILED

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen
Installment	a..5	O	For IBS: True / False, if installment is allowed	Bei IBS: True / False, ob installment erlaubt ist
Prepayment	a..5	O	For IBS: True / False, if prepayment is allowed	Bei IBS: True / False, ob prepayment erlaubt ist
Invoice	a..5	O	For IBS: True / False, if invoice is allowed	Bei IBS: True / False, ob invoice erlaubt ist
ELV	a..5	O	For IBS: True / False, if ELV is allowed	Bei IBS: True / False, ob ELV erlaubt ist
RPTransID	ans..50	O	Unique reference number from Ratepay	Eindeutige Referenznummer von Ratepay

Result parameters for Ratepay payments

Ratepay instalment calculator

The Ratepay instalment calculator (control surface implemented by the merchant) must be displayed if the end customer is expected to make a purchase by instalment. In this case the instalments are calculated on the basis of the amount + e.g. the duration (or the duration is calculated based on the instalments).

Use the following URL to display the Ratepay instalment calculator:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
Month	ans.255	C	Duration in months. Obligatory for EventToken RT.	Laufzeit in Monaten. Pflicht bei EventToken RT.
Rate	n..8	C	Monthly instalment in the smallest currency unit. Obligatory for EventToken RR.	Monatliche Rate in kleinster Währungseinheit. Pflicht bei EventToken RR.
FirstDay	n..2	O	Calendar day of first payment. Possible values are: 1, 15, 28. Default value = 28.	Kalendertag der ersten Zahlung. Mögliche Werte sind: 1, 15, 28. Standardwert = 28.
StartDate	dttm8	O	Start date of instalment payment in the format YYYYMMDD	Startdatum der Ratenzahlung im Format JJJJMMTT
DueDate	dttm8	O	Due date in the format YYYYMMDD	Fälligkeitsdatum im Format JJJJMMTT
InterestRate	n..5	O	Debit interest rate, e.g. 1370 for 13,70%	Sollzinssatz, zum Beispiel 1370 für 13,70%
EventToken	a..2	M	RT (CalculationbyTime) or RR (CalculationbyRate)	RT (CalculationbyTime) oder RR (CalculationbyRate)
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen

Parameters for Ratepay instalment calculator

Key	Format	CND	Description	Beschreibung
Status	a..50	M	INIT or FAILED	INIT oder FAILED

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen
TotalAmount	n..10	M	Total amount to be financed in the smallest currency unit	Zu finanzierender Gesamtbetrag in der kleinsten Währungseinheit
InterestAmount	n..10	M	Sum of all monthly instalments in the smallest currency unit	Summe aller monatlich gezahlten Raten in der kleinsten Währungseinheit
ServiceCharge	n..10	M	Additional financing costs in the smallest currency unit	Zusätzliche Finanzierungskosten in der kleinsten Währungseinheit
InterestRate	n..5	M	Debit interest rate, e.g. 1370 for 13,70%	Sollzinssatz, zum Beispiel 1370 für 13,70%
AnnualPercentageRate	n..5	M	Annual interest based on ServiceCharge and InterestRate	Jahreszins basierend auf ServiceCharge und InterestRate
MonthlyDebitInterest	n..5	M	Monthly debit interest based on AnnualPercentageRate	Monatlicher Zins basierend auf AnnualPercentageRate
InstallmentNumber	n..2	M	Number of monthly instalments	Anzahl Monate der Ratenzahlung
InstallmentAmount	n..10	M	Monthly amount payable in the smallest currency unit	Monatlich zu bezahlender Betrag in der kleinsten Währungseinheit
InstallmentLastAmount	n..10	M	Amount of the last rate in the smallest currency unit	Betrag der letzten Rate in der kleinsten Währungseinheit
FirstDay	n..2	O	Calendar day of first payment. Possible values are 1, 15, 28. Default value = 28.	Kalendertag der ersten Zahlung. Mögliche Werte sind 1, 15, 28. Standardwert = 28.

Result parameters for Ratepay instalment calculator

Although the configuration of the instalment calculator is firmly specified by Ratepay, it may be helpful to query this configuration before further processing in order to avoid subsequent errors. Use the following URL to do this:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
EventToken	a..2	M	RC for Rateconfiguration	RC für Rateconfiguration
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen

Parameters for querying the configuration of the Ratepay instalment calculator

Key	Format	CND	Description	Beschreibung
MinRate	n..2	O	Minimum number of instalments	Mindestanzahl der Raten
DefaultRate	n..12	O	Default rate in the smallest currency unit	Standardrate in der kleinsten Währungseinheit
MaxInterestRate	n..5	O	Maximum interest rate	Maximaler Zinssatz
MinMonth	n..2	O	Minimum running time in months	Mindestlaufzeit in Monaten
MaxMonth	n..2	O	Maximum running time in months	Maximallaufzeit in Monaten
MonthLongrun	n..2	O	Minimum running time for a long time financing	Mindestlaufzeit für eine Langzeitfinanzierung
MonthAllowed	ans..50	O	Comma-separated list of permissible running times in months	Kommaseparierte Liste mit erlaubten Laufzeiten in Monaten
FirstDay	ans..20	O	Comma-separated list of permissible start days (1, 15, 28)	Kommaseparierte Liste mit möglichen Starttagen (1, 15, 28)
LastRate	n..10	O	Minimum amount for the final instalment in the smallest currency unit	Mindestbetrag für die Abschlussrate in der kleinsten Währungseinheit
MinRateNormal	n..10	O	Minimum rate in the smallest currency unit	Mindestrate in der kleinsten Währungseinheit
MinRateLongrun	n..10	O	Minimum rate for a long term financing in the smallest currency unit	Mindestrate einer Langzeitfinanzierung in der kleinsten Währungseinheit
ServiceCharge	n..10	O	Additional financing costs in the smallest currency unit	Zusätzliche Finanzierungskosten in der kleinsten Währungseinheit
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters of the configuration query of the Ratepay instalment calculator

Create payment process

In order to create a payment transaction with Ratepay, please use the following URL:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
RPMethod	ans..10	M	Type of payment: INVOICE, INSTALLMENT or ELV	Zahlungsweise: INVOICE, INSTALLMENT oder ELV
ShoppingBasketAmount	n..10	M	Total value of shopping basket in smallest currency unit (less discount, incl. shipment etc.)	Gesamtwert des Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.)
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
DeviceToken	ans..100	O	Device token, see external documentation from Ratepay	Geräte-Token, siehe externe Dokumentation von Ratepay
ShopSystem	ans..127	O	Name of the shop system	Name des Shop-Systems
ShopSystemVersion	ans..127	O	Version name of the shop system	Versionsname des Shop-Systems
EventToken	a..2	M	R for RateInit	R für RateInit
			SEPA (ELV)	SEPA (ELV)
AccOwner	ans..55	C	Name of account holder. Mandatory for direct debit.	Name des Kontoinhabers. Pflicht bei DirectDebit.
IBAN	ans..34	C	International Bank Account Number. Mandatory for direct debit.	International Bank Account Number. Pflicht bei DirectDebit.
BIC	ans11	O	Bank Identifier Code	Bank Identifier Code. Pflicht bei DirectDebit.
AccBank	ans..27	O	Name of the financial institution	Name des Kreditinstituts
DebitPayType	a2	C	Type of payment. Mandatory for direct debit. BT = BankTransfer ; DD = DirectDebit	Zahlungsweise. Pflicht bei DirectDebit. BT = BankTransfer ; DD = DirectDebit
			Instalment payment (INSTALLMENT)	Ratenzahlung (INSTALLMENT)
InterestRate	n..5	C	Reference interest rate (value is taken from the instalment calculator). Mandatory for instalment.	Sollzinssatz (Wert ist dem Ratenrechner zu entnehmen). Pflicht bei Ratenzahlung.
InstallmentNumber	n..12	C	Number of monthly instalments (value is taken from the instalment calculator). Mandatory for instalment.	Anzahl Monate der Ratenzahlung (Wert ist dem Ratenrechner zu entnehmen). Pflicht bei Ratenzahlung.
InstallmentAmount	n..10	C	Amount payable monthly (value is taken from the instalment calculator). Mandatory for instalment.	Monatlich zu bezahlender Betrag (Wert ist dem Ratenrechner zu entnehmen). Pflicht bei Ratenzahlung.
InstallmentLastAmount	n..10	C	Amount of final instalment (value is taken from the instalment calculator). Mandatory for instalment.	Betrag der letzten Rate (Wert ist dem Ratenrechner zu entnehmen). Pflicht bei Ratenzahlung.
FirstDay	n..2	O	Calendar day of first payment. Possible values are 1, 15, 28. Default value = 28.	Kalendertag der ersten Zahlung. Mögliche Werte sind 1, 15, 28. Standardwert = 28.
TotalAmount	n..10	C	Total amount to be financed. Mandatory for instalment.	Zu finanzierender Gesamtbetrag. Pflicht bei Ratenzahlung.

Parameters for the creation of a Ratepay payment

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters for the creation of a Ratepay payment

Confirm payment transaction

In order to conform a payment transaction with Ratepay, please use the following URL:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
EventToken	a..2	M	V for verify	V für verify

Parameters for confirming a Ratepay payment

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters for confirmung a Ratepay payment

Capture a Ratepay payment transaction (full / partial capture)

In order to capture a payment transaction with Ratepay, please use the following URL:

capture.aspx

Key	Format	CND	Description	Beschreibung
ShoppingBasket	ans..1024	M	Shopping cart with items to be posted (structure - see ShoppingBasket table)	Warenkorb mit den zu buchenden Artikeln (Aufbau siehe Tabelle ShoppingBasket)
ShoppingBasketAmount	n..10	M	Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.)	Gesamtwert des aktuellen Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.)
Discount	ans..100	O	Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900	Warenkorbübergreifender Rabatt. Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Rabatt;1000;1900
ShippingProfile	ans..100	O	Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900	Versandkosten Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Versand;500;1900
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
InvoiceID	ans..50	O	Invoice number	Rechnungsnummer
TrackingID	ans..100	O	List of shipment service providers with associated parcel number. Format: SERVICE PROVIDER; PACKAGE NUMBER Example: DHL;Paket1 Other service providers/dispatch numbers are respectively delimited with a “+”. Example: DHL;Paket1+DHL;Paket2+GLS;Paket9 Caution: The shortcodes for providers are to coordinate with Ratepay!	Liste der Versanddienstleister mit zugehöriger Paketnummer. Format: DIENSTLEISTER;PAKETNUMMER Beispiel: DHL;Paket1 Weitere Dienstleister/Versandnummern werden jeweils mit einem „+“ abgegrenzt. Beispiel: DHL;Paket1+DHL;Paket2+GLS;Paket9 Achtung: Die Kürzel für die Provider sind mit Ratepay abzustimmen!
ShopSystem	ans..127	O	Name of the shop system	Name des Shop-Systems
ShopSystemVersion	ans..127	O	Version name of the shop system	Versionsname des Shop-Systems
EventToken	a..2	M	C for capture	C für Capture (Buchung)

Parameters for capture of a Ratepay payment

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters for capturing a Ratepay payment

Cancellation / return of Ratepay payments

In order to cancel a Ratepay payment partial or in full or the make changes on a payment, please use the following URL:

ratepay.aspx

Notice: There are constraints for the different actions (event tokens) regarding when actions can be carried out. Before the capture only the following are allowed: FC (full cancellation), PC (partial cancellation), CO (change order). Only after the capture are allowed FR (full return) and PR (partial return).

Key	Format	CND	Description	Beschreibung
RPMethod	ans..10	M	Type of payment: INVOICE, INSTALLMENT or ELV	Zahlungsweise: INVOICE, INSTALLMENT oder ELV
ShoppingBasket	ans..1024	C	Shopping cart with items to be cancelled (structure - see ShoppingBasket table) for EventToken FC / FR either ShoppingBasket or ShoppingBasketAmount is required	Warenkorb mit den zu stornierenden Artikeln (Aufbau siehe Tabelle ShoppingBasket) für EventToken FC / FR ist entweder ShoppingBasket oder ShoppingBasketAmount erforderlich
ShoppingBasketAmount	n..10	C	Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.) for EventToken FC / FR either ShoppingBasket or ShoppingBasketAmount is required	Gesamtwert des aktuellen Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.) für EventToken FC / FR ist entweder ShoppingBasket oder ShoppingBasketAmount erforderlich
Discount	ans..100	O	Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900	Warenkorbübergreifender Rabatt. Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Rabatt;1000;1900
ShippingProfile	ans..100	O	Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900	Versandkosten Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Versand;500;1900
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
ShopSystem	ans..127	O	Name of the shop system	Name des Shop-Systems
ShopSystemVersion	ans..127	O	Version name of the shop system	Versionsname des Shop-Systems
EventToken	a..2	M	FC for full-cancellation PC for partial-cancellation CO for change-order FR for full-return PR for partial-return	FC für full-cancellation PC für partial-cancellation CO für change-order FR für full-return PR für partial-return

Parameters for cancellation / change of a Ratepay payment

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters for cancellation / change of a Ratepay payment

Crediting Ratepay payments

In order to credit a payment transaction with Ratepay, please use the following URL:

ratepay.aspx

Key	Format	CND	Description	Beschreibung
ShoppingBasket	ans..1024	M	Shopping cart with a “CREDIT” item (structure - see ShoppingBasket table)	Warenkorb mit einem „CREDIT“-Artikel (Aufbau siehe Tabelle ShoppingBasket)
ShoppingBasketAmount	n..10	M	Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.)	Gesamtwert des aktuellen Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.)
Discount	ans..100	O	Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900	Warenkorbübergreifender Rabatt. Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Rabatt;1000;1900
ShippingProfile	ans..100	O	Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900	Versandkosten Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Versand;500;1900
Account	ans..10	O	Account identification to use separate logins (SubShops)	Account-Kennung, um gesonderte (SubShops) Logins zu nutzen
ShopSystem	ans..127	O	Name of the shop system	Name des Shop-Systems
ShopSystemVersion	ans..127	O	Version name of the shop system	Versionsname des Shop-Systems
EventToken	a..2	M	CR for Credit	CR für Credit (Gutschrift)

Parameters for crediting a Ratepay payment

Key	Format	CND	Description	Beschreibung
InfoText	ans..1024	O	Contains an infotext which can be forwarded to the customer (e.g. at refusal)	Enthält einen Info-Text, der dem Kunden weitergegeben werden kann (z.B. bei Ablehnung)
ExternalMessage	ans..256	O	Error text from Ratepay, if agreed with	Fehlertext von Ratepay, wenn mit abgesprochen
ExternalCode	ans..64	O	Error code from Ratepay, if agreed with	Fehlercode von Ratepay, wenn mit abgesprochen

Response parameters for crediting a Ratepay payment

ShoppingBasket parameter explained

The ShoppingBasket parameter describes the affected transaction items and is comprised of various parameters. The individual parameters within a shopping cart are separated with a “;”. Only enter the values and not the associated parameter name. Unused optional parameters must be transferred as an empty field. Each further item is separated from the last with a “+”. For an example see table below.

The following table describes the individual values within the ShoppingBasket:

Key	Format	CND	Description	Beschreibung
ArtNr	ans..255	C	Unique article number. Each item in the shopping cart must be clearly identifiable. Either via ArtNr or a combination of ArtNr and UniqueArticleNumber.	Eindeutige Artikelnummer. Jeder Artikel im Warenkorb muss eindeutig identifizierbar sein. Entweder über ArtNr oder eine Kombination aus ArtNr und UniqueArticleNumber.
Quantity	n..12	M	Quantity	Anzahl
Category	n..2	O	Article category (as agreed with Ratepay)	Artikelkategorie (nach Absprache mit Ratepay)
Item	ans..255	M	Article description	Artikelbeschreibung
UnitPriceGross	n..12	M	Unit price gross in smallest currency unit	Stückpreis brutto in kleinster Währungseinheit
TaxRate	n..5	M	VAT rate with 2 decimal places, e.g. 1900 for 19%	Steuersatz mit 2 Nachkommastellen, z.B. 1900 für 19%
UniqueArticleNumber	ans..50	C	Unique article number. Each item in the shopping cart must be clearly identifiable. Either via ArtNr or a combination of ArtNr and UniqueArticleNumber.	Eindeutige Artikelnummer. Jeder Artikel im Warenkorb muss eindeutig identifizierbar sein. Entweder über ArtNr oder eine Kombination aus ArtNr und UniqueArticleNumber.
Discount	n..12	O	Article-specific discount in smallest currency unit	Artikelbezogener Nachlass in kleinster Währungseinheit
DescriptionAddition	ans..511	O	Additional text for further description. Can be used in communication between Ratepay and the end customer.	Zusatztext für weitere Beschreibung. Kann in der Kommunikation zwischen Ratepay und dem Endkunden genutzt werden.

Parameters within the shopping basket

Example of a shopping basket with 3 articles:

ShoppingBasket=A;1;1;bed;10000;1900;01233;1000;blue+B;2;1;towel;3000;1900;0234;;180x200+C;5;1;pillow;1000;1900;;;

Batch processing via the interface

This section describes the parameters which must be transferred within the data set (Record) for executing a Ratepay capture or change and which information can be found within the response file about the payment status.

For Batch calls there must be considered batch versions, from which optional parameters depend. All version designations starting with „2.“ pertain calls for a group of enterprises. That means within a batch file for a particular MerchantID can be transferred transactions for other merchants with a separate Sub-MID.

Following table gives an overview of all batch versions that are possible for a specific action an their specialities:

Action	Version	Description	Beschreibung
Capture	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)
	1.1.2 / 2.1.2	with discount and shipping	mit discount und shipping
Change	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)
	1.1.2 / 2.1.2	with discount and shipping	mit discount und shipping

Description of the possible batch versions

The structure for a capture or credit within a Batch file to be submitted is the following:

HEAD,<MerchantID>,<Date>,<Version>
Ratepay,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ShoppingBasket>,<ShoppingBasketAmount>,<EventToken>,<RPMethod>(,<Discount>,<Shipping>)
Ratepay,Change,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ShoppingBasket>,<ShoppingBasketAmount>,<EventToken>,<RPMethod>(,<Discount>,<Shipping>)
FOOT,<CountRecords>,<SumAmount>

Example for Master MID function:

HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount

Key

Format

CND

Description

Beschreibung

Type

a..11

M

HEAD for Header, FOOT for Footer, Ratepay for the transactions

HEAD für Header, FOOT für Footer, Ratepay für Transaktionen

Action

a..20

M

The parameter Action defines the type of transaction:

Capture

Change (credit / change)

Der Action-Parameter definiert die Art der Transaktion:

Capture (Buchung)

Change (Gutschrift / Änderung)

Key	Format	CND	Description	Beschreibung
ShoppingBasket	ans..1024	M	Shopping cart with items to be cancelled (structure - see ShoppingBasket table) for EventToken FC / FR either ShoppingBasket or ShoppingBasketAmount is required	Warenkorb mit den zu stornierenden Artikeln (Aufbau siehe Tabelle ShoppingBasket) für EventToken FC / FR ist entweder ShoppingBasket oder ShoppingBasketAmount erforderlich
ShoppingBasketAmount	n..12	M	Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.) for EventToken FC / FR either ShoppingBasket or ShoppingBasketAmount is required	Gesamtwert des aktuellen Warenkorbs in kleinster Währungseinheit (abzüglich Rabatte, inkl. Versand u.a.) für EventToken FC / FR ist entweder ShoppingBasket oder ShoppingBasketAmount erforderlich
EventToken	a..2	M	R for RateInit CR for Credit FC for full-cancellation PC for partial-cancellation CO for change-order FR for full-return PR for partial-return	R für RateInit (Initialisierung) CR für Credit (Gutschrift) FC für full-cancellation (Vollstornierung) PC für partial-cancellation (Teilstornierung) CO für change-order (Änderung) FR für full-return (Vollrücksendung) PR für partial-return (Teilrücksendung)
RPMethod	ans..10	C	Type of payment: INVOICE, INSTALLMENT or ELV. Is not needed for capture!	Zahlungsweise: INVOICE, INSTALLMENT oder ELV. Wird bei Buchung (Capture) nicht benötigt!
Discount	ans..100	O	Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900	Warenkorbübergreifender Rabatt Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Rabatt;1000;1900
ShippingProfile	ans..100	O	Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900	Versandkosten Format: BEZEICHNUNG;BRUTTOBETRAG;STEUERSATZ Beispiel: Versand;500;1900

Description of fields within the record for Batch files

The record area within the response file for Batch transactions looks the following way:

HEAD,<MerchantID>,<Date>,<Version>
Ratepay,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ShoppingBasket>,<ShoppingBasketAmount>,<EventToken>,<RPMethod>(,<Discount>,<Shipping>),<Status>,<Code>
Ratepay,Change,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ShoppingBasket>,<ShoppingBasketAmount>,<EventToken>,<RPMethod>(,<Discount>,<Shipping>),<Status>,<Code>
FOOT,<CountRecords>,<SumAmount>

Key	Format	CND	Description	Beschreibung
Action	a..20	M	The parameter Action defines the type of transaction: Capture Change (credit / change)	Der Action-Parameter definiert die Art der Transaktion: Capture (Buchung) Change (Gutschrift / Änderung)

Description of result parameters within the record for Batch files