Ratepay
1.1 General information about RatePAY
2 1cs Online Payment System interface
2.2 RatePAY invoice and hire purchase
2.3 Initialising RatePAY payments
2.4 RatePAY instalment calculator
2.6 Confirm payment transaction
2.7 Capture a RatePAY payment transaction (full / partial capture)
2.8 Cancellation / return of RatePAY payments
2.9 Crediting RatePAY payments
1 About RatePAY
1.1 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, the 1cs Online Payment System 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, the 1cs Online Payment System offers guaranteed hire purchase within several European countries.
Logo
| Info | Type |
| 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. | Payments by Invoice and Installments |
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.
Further information can be found on the webpage of RatePAY (http://www.ratepay.com).
1.2 Process flow chart
RatePAY process flow
2 1cs Online Payment System interface
2.1 Definitions
2.1.1 Data formats
| Format | Description |
| a | alphabetical |
| as | alphabetical with special characters |
| n | numeric |
| an | alphanumeric |
| ans | alphanumeric with special characters |
| ns | numeric with special characters |
| bool | boolean expression (true or false) |
| 3 | fixed length with 3 digits/characters |
| ..3 | variable length with maximum 3 digits/characters |
| enum | enumeration of allowed values |
| dttm | ISODateTime (YYYY-MM-DDThh:mm:ss) |
2.1.1 Abbreviations
| Abbreviation | Description | Comment |
| CND | condition | |
| M | mandatory | If a parameter is mandatory, then it must be present |
| O | optional | If a parameter is optional, then it can be present, but it is not required |
| C | conditional | If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional |
Notice: Please note that the names of parameters can be returned in upper or lower case.
2.2 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.
First Cash Solution RatePAY has 5 different requests which must be carried out in the payment process depending on the situation and progress. The 1cs Online Payment System converts these requests into the corresponding RatePAY requests. In this case the following mapping applies:
| First Cash Solution request | RatePAY request | Description |
| INIT / Authorize | PAYMENT_INIT (PAYMENT_QUERY) | First Cash Solution executes automatically the request PAYMENT_INIT. If a merchant uses Integrated Payment Control (IBS) the PAYMENT_QUERY request is carried out. EventToken = A |
| Create payment (Authorize step 1) | PAYMENT_REQUEST | Initialises a purchase by instalment or purchase on account EventToken = R |
| Verify (Authorize step 2) | PAYMENT_CONFIRM | Confirms the initialisation again. First Cash Solution can also automate this request. Please leave this request out in that case (contact our support for this). 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 |
| 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 |
| 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 |
2.3 Initialising RatePAY payments
In order to initialize a RatePAY payment via server-to-server communication, please go to the following URL:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the transfer parameters to be encrypted:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| OrderDesc | ans..768 | O | Description of the goods purchased |
| ans..255 | M | Email address of the card holder | |
| CustomerID | an..30 | O | Unique customer ID in merchant system or the customer’s email address. |
| CustomerClassification | ans..8 | O | Instruction to risk management about type of customer: negative, neutral, positive, vip |
| Title | ans..45 | O | Title |
| Salutation | ans..45 | O | Salutation |
| Gender | a1 | M | Gender: Sex (M=male / F=female / U=unknown) |
| DateOfBirth | dttm8 | C | Date of birth in the format YYYYMMDD Optional for B2B (CompanyName transmitted), otherwise mandatory. |
| PhoneAreaCode | ans..30 | C | Telephone code. Mandotory if MobileAreaCode is not transmitted. |
| Phone | ans..30 | C | Phone number. Mandotory if Mobile is not transmitted. |
| FaxAreaCode | ans..30 | O | Fax area code |
| Fax | ans..30 | O | Fax number |
| MobileAreaCode | ans..30 | C | Mobile area code. Mandotory if PhoneAreaCode is not transmitted. |
| Mobile | ans..30 | C | Mobile telephone number. Mandotory if Phone is not transmitted. |
| AccOwner | ans..55 | C | Name of account holder. Mandatory for direct debit. |
| IBAN | ans..34 | C | International Bank Account Number. Mandatory for direct debit. |
| BIC | ans11 | O | Bank Identifier Code |
| AccBank | ans..27 | O | Name of the financial institution |
| Nationality | a2 | M | Country code of customer’s country of origin according to ISO-3166 alpha 2 |
| AllowCredInq | a..3 | M | Customer agrees to the passing on of his details for marketing purposes (yes / no): |
| ShopSystem | ans..127 | O | Name of the shop system |
| ShopSystemVersion | ans..127 | O | Version name of the shop system |
| ShoppingBasket | ans..1024 | M | Current shopping basket (for structure see table Shopping-Basket) |
| ShoppingBasketAmount | n..10 | M | Total value of shopping basket in smallest currency unit (less discount, incl. shipment etc.) |
| Discount | ans..100 | O | Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900 |
| ShippingProfile | ans..100 | O | Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900 |
| Account | ans..10 | O | Account identification to use separate logins (SubShops). |
| EventToken | a..2 | M | „A“ for authorization |
| Company date (B2B) | |||
| CompanyName | ans..100 | C | Company name, obligatory for B2B |
| VatID | ans..25 | C | VAT-ID, obligatory for B2B |
| CompanyID | ans..50 | O | Register of Companies number |
| LegalForm | ans..100 | O | Legal form. The value to be transmitted must be coordinated with RatePAY! |
| RegistryLocation | ans..255 | O | Company’s principal office |
| Homepage | ans..255 | O | Homepage of the company |
| Delivery data | |||
| sdFirstName | ans..100 | O | First name of the custumer |
| sdLastName | ans..100 | O | Last name of the customer |
| sdStreet | ans..100 | O | Street name and house number |
| sdStreetHouseNumber | ans..10 | O | Street number |
| sdStreetAddition | ans..50 | O | Addition in the delivery address |
| sdZIP | ans..10 | O | Postcode |
| sdCity | ans..255 | O | City |
| sdCountryCode | a2 | O | Two characters country code according to ISO 3166 |
| sdPhone | ns..32 | O | Customer’s phone number |
| Invoice data (check address) | |||
| bdFirstName | ans..100 | M | First name of the custumer |
| bdLastName | ans..100 | M | Last name of the customer |
| bdCompanyName | ans..100 | O | Name of company |
| bdStreet | ans..50 | M | Street name in the invoicing address |
| bdStreetNr | ans..10 | M | Street number of the invoicing address |
| bdStreetAddition | ans..50 | O | Address addition in the billing address |
| bdZIP | ans..10 | M | Postcode in the invoicing address |
| bdCity | ans..255 | M | Town/city of the invoicing address |
| bdCountryCode | a2 | M | Country code for the invoicing address, 2 characters according to ISO 3166 |
| bdPhone | ns..32 | M | Customer’s phone number |
| Registration address (B2B) | |||
| FirstName | ans..100 | O | First name |
| LastName | ans..100 | O | Last name |
| AddrStreet | ans..50 | C | Street. Mandatory if B2B (CompanyName is given) |
| AddrStreetNr | ans..10 | C | Street number. Mandatory if B2B (CompanyName is given) |
| AddressAddition | ans..50 | O | Address c/o |
| AddrZip | ans..10 | C | Postcode. Mandatory if B2B (CompanyName is given) |
| AddrCity | ans..32 | C | City. Mandatory if B2B (CompanyName is given) |
| AddrCountryCode | a2 | C | Two characters country code according to ISO 3166. Mandatory if B2B (CompanyName is given) |
| Fraud prevention | |||
| IPAddr | ans..15 | M | With the transferred IP address the 1cs Online Payment System can determine in which country and in which town your customer has connected with the Internet (see also IPZone). Format: 123,456,789,012 |
| DeviceToken | ans..100 | O | Device token, see external documentation from RatePAY |
Parameters for RatePAY payments
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | INIT or FAILED |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
| Installment | a..5 | O | For IBS: True / False, if installment is allowed |
| Prepayment | a..5 | O | For IBS: True / False, if prepayment is allowed |
| Invoice | a..5 | O | For IBS: True / False, if invoice is allowed |
| ELV | a..5 | O | For IBS: True / False, if ELV is allowed |
| RPTransID | ans..50 | O | Unique reference number from RatePAY |
Result parameters for RatePAY payments
2.4 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).
Enter the following URL to display the RatePAY installment calculator:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217. Please find an overview here: A1 Currency table |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| Month | ans..255 | C | Duration in months. Obligatory for EventToken RT |
| Rate | n..8 | C | Monthly instalment in the smallest currency unit. Obligatory for EventToken RR |
| FirstDay | n..2 | O | Calendar day of first payment. Possible values are 1,15,28. Default value = 28. |
| StartDate | dttm8 | O | Start date of instalment payment in the format YYYYMMDD |
| DueDate | dttm8 | O | Due date in the format YYYYMMDD |
| InterestRate | n..5 | O | Debit interest rate, e.g. 1370 for 13,70% |
| EventToken | a..2 | M | RT (CalculationbyTime) or RR (CalculationbyRate) |
| Account | ans..10 | O | Account identification to use separate logins (SubShops). |
Parameters for RatePAY instalment calculator
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | INIT or FAILED |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
| TotalAmount | n..10 | M | Total amount to be finances amount in the smallest currency unit |
| InterestAmount | n..10 | M | Sum of all monthly instalments in the smallest currency unit |
| ServiceCharge | n..10 | M | Additional financing costs in the smallest currency unit |
| InterestRate | n..5 | M | Debit interest rate, e.g. 1370 for 13,70% |
| AnnualPercentageRate | n..5 | M | Annual interest based on ServiceCharge and InterestRate |
| MonthlyDebitInterest | n..5 | M | Monthly debit interest based on AnnualPercentageRate |
| InstallmentNumber | n..2 | M | Number of monthly instalments |
| InstallmentAmount | n..10 | M | Monthly amount payable in the smallest currency unit |
| InstallmentLastAmount | n..10 | M | Amount of the last rate in the smallest currency unit |
| FirstDay | n..2 | O | Calendar day of first payment. Possible values are 1,15,28. Default value = 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. Enter the following URL to do this:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing of batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| Account | ans..10 | O | Account identification to use separate logins (SubShops). |
| EventToken | a..2 | M | RC for Rateconfiguration |
Parameters for querying the configuration of the RatePAY instalment calculator
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| MinRate | n..2 | O | Minimum number of instalments |
| DefaultRate | n..12 | O | Default rate in the smallest currency unit |
| MaxInterestRate | n..5 | O | Maximum interest rate |
| MinMonth | n..2 | O | Minimum running time in months |
| MaxMonth | n..2 | O | Maximum running time in months |
| MonthLongrun | n..2 | O | Minimum running time for a long time financing |
| MonthAllowed | ans..50 | O | Comma-separated list of permissible running times in months |
| FirstDay | ans..20 | O | Comma-separated list of permissible start days (1,15,28) |
| LastRate | n..10 | O | Minimum amount for the final instalment in the smallest currency unit |
| MinRateNormal | n..10 | O | Minimum rate in the smallest currency unit |
| MinRateLongrun | n..10 | O | Minimum rate for a long term financing in the smallest currency unit |
| ServiceCharge | n..10 | O | Additional financing costs in the smallest currency unit |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters of the configuration query of the RatePAY instalment calculator
2.5 Create payment process
In order to create a payment transaction with RatePAY, please call the following URL:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by 1cs OPS for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| RPMethod | ans..10 | M | Type of payment: INVOICE, INSTALLMENT or ELV |
| ShoppingBasketAmount | n..10 | M | Total value of shopping basket in smallest currency unit (less discount, incl. shipment etc.) |
| Account | ans..10 | O | Account identification to use separate logins (SubShops) |
| DeviceToken | ans.100 | O | Device token, see external documentation from Ratepay |
| ShopSystem | ans..127 | O | Name of the shop system |
| ShopSystemVersion | ans..127 | O | Version name of the shop system |
| EventToken | a..2 | M | R for RateInit |
| SEPA (ELV) | |||
| AccOwner | ans..55 | C | Name of account holder. Mandatory for direct debit. |
| IBAN | ans..34 | C | International Bank Account Number. Mandatory for direct debit. |
| BIC | ans11 | O | Bank Identifier Code |
| AccBank | ans..27 | O | Name of the financial institution |
| DebitPayType | a2 | C | Type of payment. Mandatory for direct debit. BT = BankTransfer ; DD = DirectDebit |
| Instalment payment (INSTALLMENT | |||
| InterestRate | n..5 | C | Reference interest rate (value is taken from the instalment calculator). Mandatory for instalment. |
| InstallmentNumber | n..12 | C | Number of monthly instalments (value is taken from the instalment calculator). Mandatory for instalment. |
| InstallmentAmount | n..10 | C | Amount payable monthly (value is taken from the instalment calculator). Mandatory for instalment. |
| InstallmentLastAmount | n..10 | C | Amount of final instalment (value is taken from the instalment calculator). Mandatory for instalment. |
| FirstDay | n..2 | O | Calendar day of first payment. Possible values are 1, 15, 28. Default value = 28. |
| TotalAmount | n..10 | C | Total amount to be financed. Mandatory for instalment. |
Parameters for the creation of a Ratepay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters for the creation of a Ratepay payment
2.6 Confirm payment transaction
In order to conform a payment transaction with Ratepay, please use the following URL:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, 1cs Online Payment System rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally this parameter has to be passed in plain language too. |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| Account | ans..10 | O | Account identification to use separate logins (SubShops) |
| EventToken | a..2 | M | V for verify |
Parameters for confirming a Ratepay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters for confirmung a Ratepay payment
2.7 Capture a Ratepay payment transaction (full / partial capture)
In order to capture a payment transaction with Ratepay, please use the following URL:
https://www.computop-paygate.com/capture.aspx
Notice: For security reasons, 1cs OPS rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by 1cs OPS for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| ReqID | ans..32 | O | To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, 1cs OPS will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the 1cs Online Payment System must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on 1cs OPS does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the 1cs Online Payment System. |
| ShoppingBasket | ans..1024 | M | Shopping cart with items to be posted (structure – see ShoppingBasket table) |
| ShoppingBasketAmount | n..10 | M | Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.) |
| Discount | ans..100 | O | Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900 |
| ShippingProfile | ans..100 | O | Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900 |
| Account | ans..10 | O | Account identification to use separate logins (SubShops) |
| InvoiceID | ans..50 | O | Invoice number |
| TrackingID | ans..10 | 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! |
| ShopSystem | ans..127 | O | Name of the shop system |
| ShopSystemVersion | ans..127 | O | Version name of the shop system |
| EventToken | a..2 | M | C for capture |
Parameters for capture of a Ratepay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters for capturing a Ratepay payment
2.8 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:
https://www.computop-paygate.com/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).
Notice: For security reasons, 1cs OPS rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by 1cs OPS for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| ReqID | ans..32 | O | To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, 1cs OPS will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the 1cs Online Payment System must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on 1cs OPS does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the 1cs Online Payment System. |
| RPMethod | ans..10 | M | Type of payment: INVOICE, INSTALLMENT or ELV |
| ShoppingBasket | ans..1024 | M | Shopping cart with items to be posted (structure – see ShoppingBasket table) For EventToken FC / FR either ShoppingBasket or ShoppingBasketAmount is required |
| ShoppingBasketAmount | n..10 | 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 |
| Discount | ans..100 | O | Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900 |
| ShippingProfile | ans..100 | O | Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900 |
| Account | ans..10 | O | Account identification to use separate logins (SubShops) |
| ShopSystem | ans..127 | O | Name of the shop system |
| ShopSystemVersion | ans..127 | O | Version name of the shop system |
| EventToken | a..2 | M | FC for full-cancellation PC for partial-cancellation CO for change-order FR for full-return PR for partial-return |
Parameters for cancellation / change of a Ratepay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters for cancellation / change of a Ratepay payment
2.9 Crediting Ratepay payments
In order to credit a payment transaction with Ratepay, please use the following URL:
https://www.computop-paygate.com/ratepay.aspx
Notice: For security reasons, 1cs Online Payment System rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter must be passed in plain language too. |
| PayID | an32 | M | ID assigned by 1cs OPS for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| ReqID | ans..32 | O | To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, 1cs OPS will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the 1cs Online Payment System must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on 1cs OPS does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the 1cs Online Payment System. |
| ShoppingBasket | ans..1024 | M | Shopping cart with a “CREDIT” item (structure – see ShoppingBasket table) |
| ShoppingBasketAmount | n..10 | M | Total value of the present shopping basket in smallest currency unit (less discount, incl. shipment etc.) |
| Discount | ans..100 | O | Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900 |
| ShippingProfile | ans..100 | O | Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900 |
| Account | ans..10 | O | Account identification to use separate logins (SubShops) |
| ShopSystem | ans..127 | O | Name of the shop system |
| ShopSystemVersion | ans..127 | O | Version name of the shop system |
| EventToken | a..2 | M | CR for Credit |
Parameters for crediting a Ratepay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
- be prepared to receive additional parameters at any time and do not check the order of parameters
- the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| InfoText | ans..1024 | O | Contains an infotext which can be forwarded to the customer (e.g. at refusal) |
| ExternalMessage | ans..256 | O | Error text from RatePAY, if agreed with First Cash Solution support |
| ExternalCode | ans..64 | O | Error code from RatePAY, if agreed with First Cash Solution support |
Response parameters for crediting a Ratepay payment
2.10 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:
| Parameter | Format | CND | Description |
| 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. |
| Quantity | n..12 | M | Quantity |
| Category | n..2 | O | Article category (as agreed with Ratepay) |
| Item | ans..255 | M | Article description |
| UnitPriceGross | n..12 | M | Unit price gross in smallest currency unit |
| TaxRate | n..5 | M | VAT rate with 2 decimal places, e.g. 1900 for 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. |
| Discount | n..12 | O | Article-specific discount in smallest currency unit |
| DescriptionAddition | ans..511 | O | Additional text for further description. Can be used in communication between Ratepay and the end customer. |
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;;180×200+C;5;1;pillow;1000;1900;;;
3. Batch processing via the interface
Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online 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 | Descripton |
| Capture | 1.0 / 2.0 | Standard version without return of parameter Code |
| 1.x / 2.x | with RefNr (valid for all versions other than 1.0) | |
| 1.1.2 / 2.1.2 | with discount and shipping | |
| Change | 1.0 / 2.0 | Standard version without return of parameter Code |
| 1.x / 2.x | with RefNr (valid for all versions other than 1.0) | |
| 1.1.2 / 2.1.2 | with discount and 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
The following table describes the individual fields and values used within the data set (record) within the batch file:
| Parameter | Format | CND | Description |
| Type | a..11 | M | HEAD for Header, FOOT for Footer, Ratepay for the transactions |
| Action | a..20 | M | The parameter Action defines the type of transaction: Capture Change (credit / change) |
| PayID | an32 | M | ID assigned by 1cs OPS for the payment |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent); Please find an overview here: A1 Currency table Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 Please find an overview here: A1 Currency table EN |
| RefNr | ns..30 | O | Merchant’s unique reference number |
| 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 |
| 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 |
| Discount | ans..100 | O | Trans-shopping cart discount Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Discount;1000;1900 |
| ShippingProfile | ans..100 | O | Shipping costs Format: DESCRIPTION; GROSS AMOUNT; VAT Example: Shipment;500;1900 |
| 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 |
| RPMethod | ans..10 | C | Type of payment: INVOICE, INSTALLMENT or ELV. Is not needed for capture! |
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>
The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified in):
| Paramter | Format | CND | Description |
| Action | a..20 | M | The parameter Action defines the type of transaction: Capture Change (credit / change) |
| PayID | an32 | M | ID assigned by 1cs OPS for this transaction |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Code | n8 | M | Error code according to 1cs Online Payment System Response Codes (A4 Error codes) |
