Webcheckout
Below you will find a sample code for your payment button. Just replace the sample values as required and you are ready to start receiving payments.
POST /pay
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_price
Required
|
string |
Payment amount: ex. 1000.00 /^[0-9]+\.[0-9]{2}$/ |
pg_currency
Required
|
string |
Currency type specified in ISO 4217 alphabetic code |
pg_country
Optional
|
string |
ISO 3166-2 country code |
pg_method
Optional
|
string |
Payment method code |
pg_email
Optional
|
string |
Payer's email |
pg_first_name
Optional
|
string |
Payer name |
pg_last_name
Optional
|
string |
Payer surname |
pg_personalid
Optional
|
string |
Payer's document number |
pg_phone
Optional
|
string |
Payer's phone number |
pg_sub_merchant_id
Optional
|
string |
Code used to distinguish between different merchants that use our service through their platform |
pg_sub_merchant_url
Optional
|
string |
Website of the merchant where the payment originates from |
pg_return_url
Optional
|
string |
Redirect url for completed payments |
pg_cancel_url
Optional
|
string |
Redirect url for when the payment is failed or canceled by the payer |
pg_language
Optional
|
string |
ISO 639-1 language |
pg_name
Optional
|
string |
Description of your product / service, which will be shown in the payment screen (Max: 255) |
pg_custom
Optional
|
string |
Flexible field, can be used to track user, inventory, etc. (Max. 255) |
API
Our API implementation offers a high level of customization, allowing you to implement a white label payment solution directly on your platform in a fast and easy way.
This implementation is based on POST calls to web services, which will deliver a response in JSON format. The response will contain the URL to which you will have to redirect your customers to start the payment process.
Signature
All requests to the payment API must be signed using the merchant's secret key with the HMAC SHA256 algorithm. The signature should be calculated using the request payload, sorted in ascending order, and adding this result in a request header named X-Pg-Sig.
Get token
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
POST /api/v2/auth/token
Response 200 OK - Content-Type: application/json
{
"token": "dce5b070ba65626dccd4ad700fdf3c1d219105a1"
}
Create payment
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_ip
Required
|
string |
IP address of the payer. |
pg_price
Required
|
string |
Payment amount: ex. 1000.00 /^[0-9]+\.[0-9]{2}$/ |
pg_currency
Required
|
string |
Currency type specified in ISO 4217 alphabetic code |
pg_country
Required
|
string |
ISO 3166-2 country code |
pg_method
Required
|
string |
Payment method code |
pg_email
Required
|
string |
Payer's email |
pg_first_name
Required
|
string |
Payer name |
pg_last_name
Required
|
string |
Payer surname |
pg_personalid
Optional
|
string |
Payer's document number |
pg_phone
Optional
|
string |
Payer's phone number |
pg_sub_merchant_id
Optional
|
string |
Code used to distinguish between different merchants that use our service through their platform |
pg_sub_merchant_url
Optional
|
string |
Website of the merchant where the payment originates from |
pg_return_url
Required
|
string |
Redirect url for completed payments |
pg_cancel_url
Required
|
string |
Redirect url for when the payment is failed or canceled by the payer |
pg_custom
Optional
|
string |
Flexible field, can be used to track user, inventory, etc. (Max. 255) |
pg_address
Optional
|
string |
Payer's Address (Max 256) |
pg_city
Optional
|
string |
Payer's City (Max 64) |
Note
Some countries have special requirements for certain payment methods.
POST /api/v2/payment/create
Response 200 OK - Content-Type: application/json
{
"data": {
"service_id": "SERVICE_ID",
"transaction_id": "b023a79c-222f-454f-9ce9-dcf9c5712f4c",
"status": "created",
"payment_method": "webpay",
"amount": "3500.00",
"currency": "CLP",
"payment_method_url": "https://gateway.payretailers.cl/pay-direct/b023a79c-222f-454f-9ce9-dcf9c5712f4c",
"custom": "Pago cuenta VIP",
"customer": {
"first_name": "Roberto",
"last_name": "Fernandez",
"email": "roberto@gmail.com",
"phone": "",
"personal_id": "",
"country": "CL"
},
"redirect_urls": {
"success_url": "http://www.mi-sitio.com/pago-ok",
"cancel_url": "http://www.mi-sitio.com/pago-cancelado"
}
}
}
Get payment status
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_token
Required
|
string |
Auth token |
transaction_id
Required
|
string |
PayRetailers transaction ID |
POST /api/v2/payment/status
Response 200 OK - Content-Type: application/json
{
"payment": {
"service_id": "SERVICE_ID",
"transaction_id": "b023a79c-222f-454f-9ce9-dcf9c5712f4c",
"status": "completed",
"payment_method": "webpay",
"amount": "3500.00",
"currency": "CLP",
"created_at": "2021-01-02 23:11:00",
"completed": "2021-01-02 23:13:00",
"custom": "Pago cuenta VIP",
"customer": {
"first_name": "Roberto",
"last_name": "Fernandez",
"email": "roberto@gmail.com",
"phone": "",
"personal_id": "",
"country": "CL"
}
}
}
OneClick
OneClick allows merchants to offer their customers the option to make payments without having to enter credit card information each time they make a purchase.
PayRetailers will NEVER store customer card details
OneClick is only available for API integrations
Sign a request
To ensure the authenticity and data integrity of incoming requests, PayRetailers requires these requests to be signed. This signature is based on a computed Hash-based Message Authentication Code (HMAC) using the payload of a request, sorted in ascending order, and a secret key, known only to you and PayRetailers.
Before sending a request to PayRetailers, you must calculate the signature and add it in the X-Pg-Sig
header. Upon receiving a request, PayRetailers calculates the same signature based on the received parameters and the stored secret key. By verifying that both signatures are the same, PayRetailers ensures that the request is not tampered with.
Enroll a card
It allows the registration of the customer's card for its later use in the commerce.
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_email
Required
|
string |
Payer's email |
pg_return_url
Required
|
string |
Redirect url for completed payments |
pg_cancel_url
Required
|
string |
Redirect url for when the payment is failed or canceled by the payer |
POST /api/v2/oneclick/register
Response 200 OK - Content-Type: application/json
{
"pg_token": "97462c4c-b807-4245-9716-d1b33acd2a5e",
"redirect_url": "https://gatewayint.paygol.com/oneclick/session/97462c4c-b807-4245-9716-d1b33acd2a5e"
}
Confirm card enrollment
At the end of the registration process by the customer, he will be redirected to the URL provided by the merchant (pg_return_url
) attaching the pg_token
parameter. To complete the enrollment process, the merchant must make a confirmation call by sending the pg_serviceid
and pg_token
parameters.
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_token
Required
|
string |
|
POST /api/v2/oneclick/confirm
Response 200 OK - Content-Type: application/json
{
"pg_oneclick_card": "f81812f9-0e1b-4998-8dab-8c4084163eba",
"pg_card_type": "visa",
"pg_card_number": "XXXXXXXXXXXX9658"
}
Authorize a transaction
Once the enrollment is done, the merchant can use the pg_card
parameter received in the enrollment to make transactions.
The payment process using a previously enrolled card is similar to the regular payment process used in an API integration, with the only difference that, for OneClick payments, the pg_oneclick_card
parameter must also be sent.
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_price
Required
|
string |
Payment amount: ex. 1000.00 /^[0-9]+\.[0-9]{2}$/ |
pg_currency
Required
|
string |
Currency type specified in ISO 4217 alphabetic code |
pg_first_name
Required
|
string |
Payer name |
pg_last_name
Required
|
string |
Payer surname |
pg_email
Required
|
string |
Payer's email |
pg_oneclick_card
Required
|
string |
Unique customer card identifier. |
POST /api/v2/oneclick/create
Response 200 OK - Content-Type: application/json
{
"data": {
"amount": 5000,
"currency": "CLP",
"customer": {
"first_name": "Roberto",
"last_name": "Fernandez",
"email": "user@site.cl",
"country": "CL"
},
"payment_method": "oneclick",
"status": "completed",
"transaction_id": "2418fa18-3e38-4adf-9a4a-ba943956bd59",
}
}
Delete an enrolled card
Allows the merchant to delete an enrolled card.
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_email
Required
|
string |
Payer's email |
pg_oneclick_card
Required
|
string |
Unique customer card identifier. |
POST /api/v2/oneclick/unregister
Response 200 OK - Content-Type: application/json
List enrolled cards
Get the enrolled cards for a customer.
Headers
X-Pg-Sig
Required
|
string |
HMAC-SHA256 request signature |
Parameters
pg_serviceid
Required
|
string |
PayRetailers merchant ID |
pg_email
Required
|
string |
Payer's email |
POST /api/v2/oneclick/cards
Response 200 OK - Content-Type: application/json
Notifications
IPN (Instant Payment Notification) is a notification that is sent from one server to another through a HTTP POST call in relation to your transactions.
To receive notifications of events in your system, you must have previously configured a notification url to which PayRetailers has access.
To guarantee the security of the exchanges, the data will be signed using the merchant secret_key .
Note
The notification URL and the secret_key can be found in the Merchant panel, Notifications section.
Confirmation
If your notification script executes very complex logic or makes calls to the network, it is possible that the waiting time will expire before PayRetailers receives the reception confirmation. Ideally, your code that handles receiving notifications (acknowledging with 2xx status code) is independent of any other logic.
Handling duplicate notifications
Notification endpoints can sometimes receive the same notification more than once. This is why we recommend that you avoid duplicate notification receipts by making your event processing idempotent.
Notifications
{
"country": "CL",
"completed_at": "2020-11-26T16:22:32-03:00",
"currency": "CLP",
"created_at": "2020-11-26T16:19:27-03:00",
"custom": "Pago cuenta VIP",
"method": "webpay",
"price": "7500.00",
"service_id": "SERVICE_ID",
"status": "completed",
"transaction_id": "ZISS-A7Q8-RE2Z-S73W",
}
Retrieve notification information