4 - API
Information regarding test URLs for Rapyd's Web Payments Page and other test information can be found in Chapter 2.
When a buyer is sent to the Rapyd Web Payments Page the following parameters must be sent with the request.
Both HTTP GET and HTTP POST can be used
4.1. Parameters
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| MerchantID | N | 1 | 9 | M | Unique merchant/online store identification issued by Rapyd. |
| Language | A | 2 | 2 | O | LanguageIS is default if parameter is not sent in. Possible values:
|
| Currency | A | 3 | 3 | M | E.g. ISK. Must match the currency associated with the merchant's contract with Rapyd. |
| AuthorizationOnly | N | 1 | 1 | M | Currently not in useMust use value 0 |
| ReferenceNumber | S | 0 | 100 | O | Unique reference number issued by merchant. |
| Product_X_Description | S | 1 | 500 | M | Text description of product. X is replaced with a number from 1 to 500. If HTTP GET is being used then it is best to HTML encode this string and URL encode it if HTTP POST is being used. Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted. |
| Product_X_Quantity | N | 1 | 5 | M | Quantity of product number X. Replace X with a number from 1 to 500. Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted. |
| Product_X_Price | D | 1 | 12 | M | Price of one unit of product number X. Use a comma as a decimal separator for currencies other than ISK. Replace X with a number from 1 to 500. Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted. |
| Product_X_Discount | D | 1 | 12 | M | Amount of discount for each unit of product number X. Use a comma as a decimal separator for currencies other than ISK. Replace X with a number from 1 to 500. Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted. |
| PaymentSuccessfulURL | S | 0 | 500 | O | URL displayed on the receipt page that is a link the user can use to return to the merchant's website. The URL may include querystring parameters. The Web Payments Page adds its own parameters to this URL that contain information about the sale. If HTTP GET is being used then this should be html encoded. See section 4.2.1.2. |
| PaymentSuccessfulURLText | S | 0 | 500 | O | Text displayed by the link (PaymentSuccessfulURL), which is displayed on the receipt page. |
| PaymentSuccessfulAutomaticRedirect | N | 1 | 1 | O | 0 or 1. Indicates whether or not to redirect the user automatically to PaymentSuccessfulURL if payment is successful. Note! If this parameter is set to 1 then the merchant/online store must display its own receipt/confirmation for the sale. |
| PaymentSuccessfulServerSideURL | S | 0 | 500 | O | A URL that Rapyd requests to inform the merchant that payment was successful. The URL may include parameters. This page must return a response (HTTP status 200) and be on port 80 (HTTP) or 443 (HTTPS). The Web Payments Page adds its own parameters to this URL that contain information about the sale. If HTTP GET is being used then this should be html encoded. See section 4.2.1.2. |
| PaymentCancelledURL | S | 0 | 500 | O | URL which the user is sent to if payment is cancelled, i.e. the ”Cancel”/”Hætta við” button is clicked. If HTTP GET is being used then this should be HTML encoded. |
| DigitalSignature | S | 0 | 500 | M | MD5/SHA256 hash which is used to ensure the validity of the information sent to the Web Payments Page. See section 4.2.1.1. |
| SessionExpiredTimeoutInSeconds | N | 0 | 9 | O | If this value is sent in then the user is redirected to SessionExpiredRedirectURL when the time has expired. |
| SessionExpiredRedirectURL | S | 0 | 500 | O | URL that user is sent to if session expires. If HTTP GET is being used then this should be HTML encoded. |
| DisplayBuyerInfo | N | 1 | 1 | O | 0 or 1. Indicates whether or not to display input fields for buyer's ssn, name, address, postal code, city, country, phone number, e-mail address and comments. |
| RequireSSN | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's ssn should be a required field. |
| RequireName | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's name should be a required field. |
| RequireAddress | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's address should be a required field. |
| RequirePostalCode | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's postal code should be a required field. |
| RequireCity | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's city should be a required field. |
| RequireCountry | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's country should be a required field. |
| RequirePhone | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's phone number should be a required field. |
| RequireEmail | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's e-mail address should be a required field. |
| RequireComments | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's comments should be a required field. |
| HideSSN | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's ssn should be hidden. |
| HideName | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's name should be hidden. |
| HideAddress | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's address should be hidden. |
| HidePostalCode | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's postal code should be hidden. |
| HideCity | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's city should be hidden. |
| HideCountry | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's country should be hidden. |
| HidePhone | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's phone number should be hidden. |
| HideEmail | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's e-mail address should be hidden. |
| HideComments | N | 1 | 1 | O | 0 or 1. Indicates whether or not input field for buyer's comments should be hidden. |
| IsCardLoan | N | 1 | 1 | O | 0 or 1. Indicates whether or not card loan is to be used for the purchase. If this field is empty the payment will be made with a credit card. The amount of the loan needs to be higher than 30.000 kr. to be successfully created. |
| MerchantName | N | 0 | 100 | O | The merchant name is needed if card loan is to be used. See chapter 4.2.1.3. |
| IsInterestFree | N | 1 | 1 | O | 0 or 1. Indicates whether or not the card loan is interest free. If this value is empty, the loan is created according to the merchants contract with Rapyd. |
| CreateVirtualCardOnly | N | 1 | 1 | O | 0 or 1. Indicates whether or not the payment page should only be used to create new virtual card. Note! If this parameter is set to 1 then only new virtual card is created and no payment is made. |
4.1.1 - DigitalSignature
MD5/SHA256 hash to ensure the validity of the information sent to the Web Payments Page.
The Web Payments Page calculates the MD5/SHA256 for the same sale and compares it to the submitted hash.
The components of the string used to seed the MD5/SHA256 hash must be ordered in the following way:
VerificationCode (Öryggisnúmer) + AuthorizationOnly + Product_x_y + //only when CreateVirtualCardOnly=0 or is omitted* MerchantID + ReferenceNumber + PaymentSuccessfulURL + PaymentSuccessfulServerSideURL + Currency + IsInterestFree //only when creating card loan*
Where Product_x_y is a list of all the products in the following format:
Product_1_Quantity + Product_1_Price + Product_1_Discount + Product_2_Quantity + Product_2_Price + Product_2_Discount + etc.
Info
If card loan is to be created with IsCardLoan=1 and IsInterestFree parameter is used and SHA256, then the value for IsInterestFree needs to be appended to the DigitalSignature string, i.e. 1 or 0. Otherwise it should not be added to the string.
If CreateVirtualCardOnly parameter is used and is set as 1 then the Product_x_y should be omitted from the calculation of DigitalSignature.
Attention
It is important to use SHA256, but not MD5 when connecting to the payment page because at some point in the near future the support for MD5 will be removed from the payment page.
4.1.1.1 - Example
Using the following values:
VerificationCode: 2ef8ec654c (Information about the verification code can be found on Rapyd's Service Web under Greiðslusíða -> Upplýsingar) AuthorizationOnly: 0 Product_1_Quantity: 2 Product_1_Price: 1500 Product_1_Discount: 0 Product_2_Quantity: 1 Product_2_Price: 1000 Product_2_Discount: 0 MerchantID: 207 (MerchantID/VefverslunID is on Rapyd's Service Web under Greiðslusíða -> Upplýsingar) ReferenceNumber: 456 PaymentSuccessfulURL: http://www.minsida.is/takkfyrir PaymentSuccessfulServerSideURL: http://www.minsida.is/sale.aspx?c=8282&ref=232 Currency: ISK
The string will be:
2ef8ec654c0215000110000207456http://www.minsida.is/takkfyrirhttp://www.minsida.is/sale.aspx?c=8282&ref=232ISK
The MD5 hash for this string is A704F243D9373D6F757257544781FD76 and that is the value for DigitalSignature.
The following values are also valid for each corresponding hash type:
| Hash | Value |
|---|---|
| MD5 | A704F243D9373D6F757257544781FD76 |
| MD5 ASCII | 85a55dc4948a4e0139c8951224df8d5f |
| SHA256 | c5e360e87eb1a6b402718d82904bc2b08c51bc3be92867db5b5eacb3483fe58f |
| SHA256 ASCII | 8573f2a43f4d5fed99aaee4c8d098f14903afaf709ea1e0e7840e5e56edd962a |
If the creation of a digital signature fails, check that the correct MD5/SHA256 function is being used.
Another example for the string "abc":
| Hash | Value |
|---|---|
| Nothing | abc |
| MD5 | CE1473CF80C6B3FDA8E3DFC006ADC315 |
| MD5 ASCII | 900150983cd24fb0d6963f7d28e17f72 |
| SHA256 | 13e228567e8249fce53337f25d7970de3bd68ab2653424c7b8f9fd05e33caedf |
| SHA256 ASCII | ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad |
4.1.2 - PaymentSuccesfulURL and PaymentSuccesfulServerSideURL
If the parameters PaymentSuccessfulURL or PaymentSuccessfulServerSideURL were sent in then the following querystring parameters are added to the URLs:
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| CardType | AN | - | - | - | Card type. Examples:
|
| CardNumberMasked | S | - | - | - | For PaymentSuccessfulURL then this is the last 4 numbers in the card number with * symbols in front. For PaymentSuccessfulServerSideURL then this is the first 6 and last 4 numbers in the card number with * symbols in between. |
| Date | S | - | - | - | Date of sale Format: dd.MM.yyyy |
| AuthorizationNumber | AN | - | - | - | Authorization number |
| TransactionNumber | N | - | - | - | Transaction number. |
| SaleID | S | - | - | - | GUID created by the Web Payments Page. |
| ReferenceNumber | S | - | - | - | Merchant's reference number. |
| DigitalSignatureResponse | S | - | - | - | MD5/SHA256 hash of the string created by concatenating VerificationCode+ReferenceNumber. It is important that the value of DigitalSignatureResponse is calculated on the page that Rapyd requests and that the value is compared with the value sent by Rapyd to ensure that this is not a case of theft, i.e. an attempt to create a fraudulent sales link. |
| ContractNumber | N | - | - | - | Contract number for sale. |
| ContractType | S | - | - | - | Type of contract for sale. ORUGGS for regular Web Payment Page contract |
| CardLoanNumber | S | - | - | - | Card loan number for sale. |
| CardTypeCode | N | - | - | - | Three digit code for the type of card. |
| SSN | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's SSN is returned (if that field was filled out). |
| Name | S | - | - | - | If DisplayBuyerInfo is 1 then the buyer's name is returned (if that field was filled out). |
| Address | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's address is returned (if that field was filled out). |
| PostalCode | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's postal code is returned (if that field was filled out). |
| City | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's city is returned (if that field was filled out). |
| Country | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's country is returned (if that field was filled out). |
| Phone | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's phone number is returned (if that field was filled out). |
| N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's e-mail address is returned (if that field was filled out). | |
| Comments | N | - | - | - | If DisplayBuyerInfo is 1 then the buyer's comments are returned (if that field was filled out). |
| VirtualCard | AN | - | - | - | If CreateVirtualCardOnly is 1 then the virtual card is returned. |
4.1.3 - IsCardLoan and MerchantName
If card loan is to be used, the merchant name is needed.
If not, the parameter can be empty.
4.1.4 - CreateVirtualCardOnly
If the payment page is to be used to create virtual card by sending CreateVirtualCardOnly parameter as 1 then the following parameters are returned in PaymentSuccesfulURL og PaymentSuccesfulServerSideURL:
CardNumberMasked ReferenceNumber DigitalSignatureResponse ContractNumber VirtualCard