Register

In order to enable payment for the customer, you must register an order first.

Register

POST https://api.payvalida.com/api/v3/porders

Sandbox URL: https://api-test.payvalida.com/api/v3/porders This method creates the payment order in our system. The checkout parameter indicates the URL where the customer can complete the payment.

Path Parameters

Name	Type	Description
merchant*	string	ID of the commerce in Payvalida. Max. 50 characters.
email*	string	Customer's email. Max. 100 characters.
country*	number	Country code. 3 characters.
order*	string	Generated order's ID. Max. 200 characters.
reference*	string	Order's reference number. this field cant be alphanumeric. It helps the customer identify it on the payment process. Max 25 characters.
money*	string	Currency's code of the order. Max 3 characters.
amount*	number	Order's amount. Only accepts integers.
description*	string	Short description of the order. Max. 250 characters.
method	string	Selected payment method by the customer. Max. 25 characters
language	string	Language of the messages and responses. 2 characters.
recurrent*	boolean	Indicates whether the order is recurrent.(only apply to cash payments)
expiration*	string	Order's expiration date, must follow the format DD/MM/YYYY. It can't neither surpass 30 days nor be from a date before the registration of the order.
iva	number	Percentage amount corresponding to the VAT/IVA of the order.
checksum*	string	Checksum encoded in SHA512 (email+country+order+ money+amount+FIXED_HASH). 512 characters.
user_di	number	Identification of the customer. Max. 15 characters.
user_type_di	string	ID type of the customer. Max. 3 caracteres.
user_name	string	Customer's name. Max. 25 characters.
redirect_timeout	number	Timeout amount for the redirection in milliseconds. Max. 5 characters.

200 The execution returns a JSON following this structure:

{  
   "CODE":"0000",
   "DATA":{  
      "OrdenID":"p0000101",
      "Monto":"45000.0",
      "PVordenID":"95601",
      "Referencia":"989898101",
      "Operacion":"CREADA",
       "checkout":"checkout.payvalida.com/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJNRVJDSEFOVF9DRUwiOiIzMTc2ODI3MzQxIiwiT1JERVJfTUVUSE9EIjoiZWZlY3R5IiwiTUVSQ0hBTlRfQ09ERSI6MjU0LCJNRVJDSEFOVF9FTUFJTCI6ImhyZXN0cmVwb0BwYXl2YWxpZGEuY29tIiwiaXNzIjoiYXV0aDAiLCJNRVJDSEFOVF9MT0dPIjoiaHR0cHM6Ly9zMy5hbWF6b25hd3MuY29tL3ZhbGlkZGF3ZWIvZXZlbnRvcy9mZW5hbGNvYnJhLnBuZyIsIk1FUkNIQU5UX1VSTF9SRVRVUk4iOiJ3d3cucGludmFsaWRkYS5jb20uY28iLCJNRVJDSEFOVF9OQU1FIjoiSGVybmFuIFJwbyAoQ09MKSIsIk9SREVSX0JSSUVGIjoiVGVzdCBSRVNUZnVsbCBQdXJjaGFzZSBPcmRlciBQT1NUIiwiTUVSQ0hBTlRfVEVMIjoiMjg4MDUzOSIsIk9SREVSX0NVUlJFTkNZIjoiQ09QIiwiT1JERVJfQU1PVVQiOiIxMCwwMDAuMDAiLCJleHAiOjE1MzA0MDE1MzgsIk9SREVSX1JFRkVSRU5DRSI6IjQyMzEzIn0.QVsZwm-2BIkK-5RgrAX2NuwGqmHSNHD_zw91i1hcSc8"
   },
   "DESC":"OK"
}

Details

• merchant: UID of the commerce in Payvalida, every commerce has an assigned FIXED_HASH, only known by Payvalida and the commerce itself.

• email: email of the customer. This is used in order to send notifications associated with the orders.

• country: code of the country associated with the order.

• order: UID of the order, in alphanumeric and generated by the commerce. Using this code, Payvalida con notify and monitor the payment of it.

• reference: this identifier can be generated either automatically by Payvalida or by the merchant. The customer uses this identifier to complete the payment. Maximum length:

  • Colombia : 15.
  • Costa Rica : 16.
  • Ecuador : 16.
  • Perú : 11.
  • Guatemala : 16.
• money: currency of the order. Please consult our country and currency codes table

• amount: amount of the order. If the amount is in USD, our system converts it to each country's legal currency.

• description: short description of the order.

• method: payment method. If it's indicated, our checkout shows the instructions to complete the payment using the designated method, if its omitted, it shows all the payment methods available for the commerce.

• recurrent: indicates if an order is recurrent. A recurrent order never expires and it's always available for payment.

• expiration: expiration date for the order, after it the order will change status to expired.

• iva: if the designated payment method is credit card, you must indicate this value for the reteIVA calculation (Only required for operations in Colombia).

• checksum: verifies the identity of the commerce.

• user_di: identification number of the customer.

• user_type_di: type of identification of the customer.

• user_name: name of the customer as shown in the ID (doesn't accept special characters nor accents).

• redirect_timeout: waiting time for auto redirection to the commerce's website when the payment is complete. Applies for CC and PSE (Recommended: 15000 ms).

The commerce (merchant) id and the FIXED_HASH are provided when you create an account in our platform.

Examples

• Request

curl --location --request POST 'https://api-test.payvalida.com/api/v3/porders'
--header 'Content-Type: application/json'
--data-raw '{ 
    "merchant": "kuanto", 
    "email": "[e-mail]", 
    "country": 343, 
    "order": "999999991", 
    "reference": "46534512", 
    "money": "COP", 
    "amount": "10500", 
    "description": "Orden de prueba", 
    "method": "", 
    "language": "es", 
    "recurrent": true, 
    "expiration": "27/12/2020", 
    "iva": "0", 
    "checksum": "96C79878E0CDC0C525090281141874D7494E0194B33E0E373DC412DD31AAD32B5DB2C681441C8007B2FCAF0873BBF2C8BFDB4A6E7D04DB8E52A843A30D6CFF08", 
    "user_di": "94320444", 
    "user_type_di": "CC", 
    "user_name": "NombreUsuario", 
    "redirect_timeout": "300000" }'

• Go

package main
import (
	"bytes"
	"crypto/sha512"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"math/rand"
	"net/http"
	"time"
)
type Request struct {
	Country         int    `json:"country,omitempty"`
	Email           string `json:"email,omitempty"`
	Merchant        string `json:"merchant,omitempty"`
	Order           string `json:"order,omitempty"`
	Reference       string `json:"reference,omitempty"`
	Money           string `json:"money,omitempty"`
	Amount          string `json:"amount,omitempty"`
	Description     string `json:"description,omitempty"`
	Language        string `json:"language,omitempty"`
	Recurrent       bool   `json:"recurrent,omitempty"`
	Expiration      string `json:"expiration,omitempty"`
	Method          string `json:"method,omitempty"`
	Iva             string `json:"iva,omitempty"`
	Checksum        string `json:"checksum,omitempty"`
	UserDI          string `json:"user_di,omitempty"`
	UserTypeDI      string `json:"user_type_di,omitempty"`
	RedirectTimeout string `json:"redirect_timeout,omitempty"`
	UserName        string `json:"user_name,omitempty"`
}
func main() {
	url := "https://api-test.payvalida.com/api/v3/porders"
	method := "POST"
	email := "[e-mail]"
	country := "343"
	order := "test" + fmt.Sprint(rand.Intn(999999999))
	money := "COP"
	amount := "20000"
	fixedHash := "xxccc_b0b20707cca2b283b5844e77cadf2b5813bd923362b91583c95b736c8763937c0e0df27e9b730c404eeac6484666430f6042c043089135e8d3e76f2e86a82c38"
	Paysha512 := sha512.Sum512([]byte(email + country + order + money + amount + fixedHash))
	checksum := hex.EncodeToString(Paysha512[:])
	date := time.Now()
	expiration := date.AddDate(0, 0, 2)
	request := Request{
		Country:         343,
		Email:           email,
		Merchant:        "kuanto",
		Order:           order,
		Reference:       "",
		Money:           money,
		Amount:          amount,
		Description:     "Test pruebas unitarias",
		Language:        "es",
		Recurrent:       false,
		Expiration:      expiration.Format("02/01/2006"),
		Method:          "",
		Iva:             "0",
		Checksum:        checksum,
		UserDI:          "90000000",
		UserTypeDI:      "CC",
		RedirectTimeout: "150000",
		UserName:        "devPayvalida",
	}
	json, err := json.Marshal(request)
	if err != nil {
		fmt.Println(err)
		return
	}
	client := &http.Client{}
	req, err := http.NewRequest(method, url, bytes.NewBuffer(json))
	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()
	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

• PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-test.payvalida.com/api/v3/porders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n    \"merchant\": \"kuanto\",\n    \"email\": \"[e-mail]\",\n    \"country\": 343,\n    \"order\": \"999999991\",\n    \"reference\": \"46534512\",\n    \"money\": \"COP\",\n    \"amount\": \"10500\",\n    \"description\": \"Orden de prueba\",\n    \"method\": \"\",\n    \"language\": \"es\",\n    \"recurrent\": true,\n    \"expiration\": \"27/12/2020\",\n    \"iva\": \"0\",\n    \"checksum\": \"96C79878E0CDC0C525090281141874D7494E0194B33E0E373DC412DD31AAD32B5DB2C681441C8007B2FCAF0873BBF2C8BFDB4A6E7D04DB8E52A843A30D6CFF08\",\n    \"user_di\": \"94320444\",\n    \"user_type_di\": \"CC\",\n    \"user_name\": \"NombreUsuario\",\n    \"redirect_timeout\": \"300000\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

• Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"merchant\": \"kuanto\",\n    \"email\": \"[e-mail]\",\n    \"country\": 343,\n    \"order\": \"999999991\",\n    \"reference\": \"46534512\",\n    \"money\": \"COP\",\n    \"amount\": \"10500\",\n    \"description\": \"Orden de prueba\",\n    \"method\": \"\",\n    \"language\": \"es\",\n    \"recurrent\": true,\n    \"expiration\": \"27/12/2020\",\n    \"iva\": \"0\",\n    \"checksum\": \"96C79878E0CDC0C525090281141874D7494E0194B33E0E373DC412DD31AAD32B5DB2C681441C8007B2FCAF0873BBF2C8BFDB4A6E7D04DB8E52A843A30D6CFF08\",\n    \"user_di\": \"94320444\",\n    \"user_type_di\": \"CC\",\n    \"user_name\": \"NombreUsuario\",\n    \"redirect_timeout\": \"300000\"\n}");
Request request = new Request.Builder()
  .url("https://api-test.payvalida.com/api/v3/porders")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

• Python

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api-test.payvalida.com")
payload = "{\n    \"merchant\": \"kuanto\",\n    \"email\": \"[e-mail]\",\n    \"country\": 343,\n    \"order\": \"999999991\",\n    \"reference\": \"46534512\",\n    \"money\": \"COP\",\n    \"amount\": \"10500\",\n    \"description\": \"Orden de prueba\",\n    \"method\": \"\",\n    \"language\": \"es\",\n    \"recurrent\": true,\n    \"expiration\": \"27/12/2020\",\n    \"iva\": \"0\",\n    \"checksum\": \"96C79878E0CDC0C525090281141874D7494E0194B33E0E373DC412DD31AAD32B5DB2C681441C8007B2FCAF0873BBF2C8BFDB4A6E7D04DB8E52A843A30D6CFF08\",\n    \"user_di\": \"94320444\",\n    \"user_type_di\": \"CC\",\n    \"user_name\": \"NombreUsuario\",\n    \"redirect_timeout\": \"300000\"\n}"
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/v3/porders", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

• JavaScript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({"merchant":"kuanto","email":"[e-mail]","country":343,"order":"999999991","reference":"46534512","money":"COP","amount":"10500","description":"Orden de prueba","method":"","language":"es","recurrent":true,"expiration":"27/12/2020","iva":"0","checksum":"96C79878E0CDC0C525090281141874D7494E0194B33E0E373DC412DD31AAD32B5DB2C681441C8007B2FCAF0873BBF2C8BFDB4A6E7D04DB8E52A843A30D6CFF08","user_di":"94320444","user_type_di":"CC","user_name":"NombreUsuario","redirect_timeout":"300000"});
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};
fetch("https://api-test.payvalida.com/api/v3/porders", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));