API Reference

ID: 36 - Bank Transfer (COP)

Channel: 36

Provider: Openpay - BBVA

Payment Method: Multi-APM — Card, PSE, Cash (Store), Payment Link

Available Currencies

NameCodeCountry
Colombian pesoCOPColombia

Request example

curl --location 'https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php' \
--form 'public_key="YOUR_PUBLIC_KEY"' \
--form 'time="2024-07-17 16:33:11"' \
--form 'amount="2000"' \
--form 'currency="COP"' \
--form 'trans_id="1"' \
--form 'time_expired="120"' \
--form 'url_ok="https://bit.ly/3S4I7iR"' \
--form 'url_error="https://bit.ly/3S5aOwc"' \
--form 'channel="33"' \
--form 'signature="YOUR_SIGNATURE"' \
--form 'shopper_information="{\"Phone\": \"3044914743\", \"email\": \"[email protected]\", \"country\": \"COL\", \"country_code\": \"+57\", \"name_shopper\": \"Jairo milano\", \"Num_doc_identi\": \"5004887414\", \"type_doc_identi\": \"TI\", \"last_name_Shopper\": \"Jairo milano\"}"'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php',
  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 => array('public_key' => 'YOUR_PUBLIC_KEY','time' => '2024-07-17 16:33:11','amount' => '2000','currency' => 'COP','trans_id' => '1','time_expired' => '120','url_ok' => 'https://bit.ly/3S4I7iR','url_error' => 'https://bit.ly/3S5aOwc','channel' => '33','signature' => 'YOUR_SIGNATURE','shopper_information' => '{"Phone": "3044914743", "email": "[email protected]", "country": "COL", "country_code": "+57", "name_shopper": "Jairo milano", "Num_doc_identi": "5004887414", "type_doc_identi": "TI", "last_name_Shopper": "Jairo milano"}'),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests

url = "https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php"

payload = {'public_key': 'YOUR_PUBLIC_KEY',
'time': '2024-07-17 16:33:11',
'amount': '2000',
'currency': 'COP',
'trans_id': '1',
'time_expired': '120',
'url_ok': 'https://bit.ly/3S4I7iR',
'url_error': 'https://bit.ly/3S5aOwc',
'channel': '33',
'signature': 'YOUR_SIGNATURE',
'shopper_information': '{"Phone": "3044914743", "email": "[email protected]", "country": "COL", "country_code": "+57", "name_shopper": "Jairo milano", "Num_doc_identi": "5004887414", "type_doc_identi": "TI", "last_name_Shopper": "Jairo milano"}'}
files=[

]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php',
  'headers': {
  },
  formData: {
    'public_key': 'YOUR_PUBLIC_KEY',
    'time': '2024-07-17 16:33:11',
    'amount': '2000',
    'currency': 'COP',
    'trans_id': '1',
    'time_expired': '120',
    'url_ok': 'https://bit.ly/3S4I7iR',
    'url_error': 'https://bit.ly/3S5aOwc',
    'channel': '33',
    'signature': 'YOUR_SIGNATURE',
    'shopper_information': '{"Phone": "3044914743", "email": "[email protected]", "country": "COL", "country_code": "+57", "name_shopper": "Jairo milano", "Num_doc_identi": "5004887414", "type_doc_identi": "TI", "last_name_Shopper": "Jairo milano"}'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Mandatory Data

AttributeMandatoryData typeDescription
public_keyTrueString (255)Public key, unique value that identifies the commerce
timeTrueDatetimeRequest data time
channelTrueIntegerPayment Channel
amountTrueDoubleThe amount of the transaction. Min amount: 1000
currencyTrueString (3)Transaction currency code
trans_idTrueString (255)Transaction id
time_expiredTrueString (255)Time in minutes to expire the token. Value given in minutes. Minimum Suggested: Online: 30 minutes Cash: 2 hours For Brazil: Online: 2 hours Cash 24 hrs
url_okTrueString (255)URL where shopper will be redirected from the online banking if payment was successful (Must be Https)
url_errorTrueString (255)URL where shopper will be redirected from the online banking if payment was wrong.(Must be Https)
signatureTrueString (255)Signature hash256: Review signature calculation
shopper_informationTrueJSON StringJSON String Data: Review JSON index & format

shopper_information JSON format

📘

Field shopper_information must be send in string format (JSON encode).

{
        "Phone": "3044914743",
        "email": "[email protected]",
        "country": "COL",
        "country_code": "+57",
        "name_shopper": "Jairo milano",
        "Num_doc_identi": "5004887414",
        "type_doc_identi": "TI",
        "last_name_Shopper": "Jairo milano"
}

The shopper_information field is a column corresponding to a json with the next keys:

ParameterMandatoryData TypeDescription
name_shopperTrueString (255)Shopper's name
last_name_ShopperTrueString (255)Shopper's last name
type_doc_identiTrueString (255)Identification document
Num_doc_identiTrueString (255)Identification document number
emailTrueString (255)Shopper's e-mail
country_codeTrueString (10)Country's phone code (Ex. +57)
PhoneTrueString (20)Shopper's phone number
countryTruestring (20)Shopper's country

Filters

Using the parameter filter_by, the response can be biased toward a single payment method.

filter_by valueStored filtersBehaviour
(omitted)''Unified hosted checkout (PSE / card / store).
checkout / all''Same as omitted.
cardcardCard flow — hosted form (confirm: false) or tokenised charge if openpay_source_id is present.
bank_accountbank_accountPSE: creates a charge with method: bank_account and redirects the shopper to the bank.
cashcashCash / convenience store (charge with method: store).
linklinkHosted checkout biased to store (redirect_store_payment, attempts .../store_confirm URL).

Invalid values respond with HTTP 400 and code = INVALID_FILTER_BY.

📘

For cash transactions, a PDF voucher is generated. The end-user must present this document at the store or authorized collection point to successfully complete the payment.


PSE flow (filter_by=bank_account)

For PSE, the bank list is rendered by OpenPay's own page after the redirect; JustPay does not need to fetch banks beforehand. The legacy endpoint api/banks/openpay/pse.php exists for compatibility but is not part of the current flo

Requirements for PSE on this channel:

  • filter_by=bank_account.
  • shopper_information must include adress_shopper (or alias address) and city_shopper (or alias city), in addition to the mandatory fields listed above.
  • shopper_information.Phone must be exactly 10 digits; otherwise the API responds with SHOPPER_INVALID_PHONE (400).

PSE payload example

curl --location 'https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php' \
--form 'public_key="zyssglikvtltbd2se2hudwl50jjomil2uytp7tpvjtxyfdw469jagk8yvnex9jks"' \
--form 'time="2024-07-17 16:33:11"' \
--form 'amount="2000"' \
--form 'currency="COP"' \
--form 'trans_id="1"' \
--form 'time_expired="120"' \
--form 'url_ok="https://bit.ly/3S4I7iR"' \
--form 'url_error="https://bit.ly/3S5aOwc"' \
--form 'channel="36"' \
--form 'signature="1000ee827bea1422a46f108da3ef8f57bbcda11569c2420c66ae42071ac1083d"' \
--form 'shopper_information="{
        \"Phone\": \"3001234567\",
        \"email\": \"[email protected]\",
        \"name_shopper\": \"Fulano\",
        \"Num_doc_identi\": \"1234567890\",
        \"type_doc_identi\": \"CC\",
        \"last_name_Shopper\": \"Da Silva\",
        \"country\": \"COL\",
        \"country_code\": \"+57\",
        \"adress_shopper\": \"Calle 123 #45-67\",
        \"city_shopper\": \"Bogotá\"
       }"' \
--form 'filter_by="bank_account"'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
    'public_key'  => 'zyssglikvtltbd2se2hudwl50jjomil2uytp7tpvjtxyfdw469jagk8yvnex9jks',
    'time'        => '2024-07-17 16:33:11',
    'amount'      => '2000',
    'currency'    => 'COP',
    'trans_id'    => '1',
    'time_expired'=> '120',
    'url_ok'      => 'https://bit.ly/3S4I7iR',
    'url_error'   => 'https://bit.ly/3S5aOwc',
    'channel'     => '36',
    'signature'   => '1000ee827bea1422a46f108da3ef8f57bbcda11569c2420c66ae42071ac1083d',
    'shopper_information' => '{ "Phone": "3001234567", "email": "[email protected]", "name_shopper": "Fulano", "Num_doc_identi": "1234567890", "type_doc_identi": "CC", "last_name_Shopper": "Da Silva", "country": "COL", "country_code": "+57", "adress_shopper": "Calle 123 #45-67", "city_shopper": "Bogotá" }',
    'filter_by'   => 'bank_account',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
import requests

url = "https://uat-payments.alps.cl/justpay/check-out/SecurePayment.php"

payload = {
    'public_key': 'zyssglikvtltbd2se2hudwl50jjomil2uytp7tpvjtxyfdw469jagk8yvnex9jks',
    'time': '2024-07-17 16:33:11',
    'amount': '2000',
    'currency': 'COP',
    'trans_id': '1',
    'time_expired': '120',
    'url_ok': 'https://bit.ly/3S4I7iR',
    'url_error': 'https://bit.ly/3S5aOwc',
    'channel': '36',
    'signature': '1000ee827bea1422a46f108da3ef8f57bbcda11569c2420c66ae42071ac1083d',
    'shopper_information': '{ "Phone": "3001234567", "email": "[email protected]", "name_shopper": "Fulano", "Num_doc_identi": "1234567890", "type_doc_identi": "CC", "last_name_Shopper": "Da Silva", "country": "COL", "country_code": "+57", "adress_shopper": "Calle 123 #45-67", "city_shopper": "Bogotá" }',
    'filter_by': 'bank_account',
}

response = requests.request("POST", url, data=payload)
print(response.text)

The successful response includes a redirect URL pointing to OpenPay's PSE selection screen, where the shopper picks the bank.


Testing

Openpay provides a sandbox environment that allows you to simulate successful and failed transactions before going live.

This environment is intended to help you validate your integration, test error handling, and verify webhook notifications.


Card Charges

Use the following card numbers to simulate successful and failed payments.

Valid Test Cards

Card NumberBrandIssuing Bank
4111111111111111VisaBANAMEX
4242424242424242VisaBANCO DE COLOMBIA
5555555555554444MasterCardBANCO SANTANDER SERFIN
5105105105105100MasterCardSCOTIABANK
345678000000007American ExpressAMERICAN EXPRESS
341111111111111American ExpressAMERICAN EXPRESS
343434343434343American ExpressAMERICAN EXPRESS
5062541600005232CarnetN/A
5064050100000063CarnetN/A
5064510000300020CarnetN/A

Note: Any other card number will return an error.

Expiration Dates and CVV

Use:

  • Any expiration date later than the current month.
  • Any 3-digit CVV for Visa and MasterCard.
  • Any 4-digit CVV for American Express.

Invalid Test Cards

Use the following card numbers to simulate specific errors.

Card NumberError CodeDescription
42222222222222203001The card was declined.
40000000000000693002The card has expired.
44444444444444483003The card has insufficient funds.
40000000000001193004The card has been reported as stolen.
40000000000000443005Rejected by the fraud prevention system.
54545454545454543005Rejected by the fraud prevention system.
3400000000000093001The card was declined.
3737373737373743002The card has expired.
3700000000000023003The card has insufficient funds.

Errors

HTTPcodeCause
400INVALID_FILTER_BYfilter_by is not one of cash, card, bank_account, link, checkout, all.
400SHOPPER_PSE_ADDRESS_REQUIREDPSE without adress_shopper / city_shopper (or aliases address / city).
400SHOPPER_INVALID_PHONEPhone is not 10 digits when filter_by=bank_account, or fails general phone validator.
400SHOPPER_INVALID_COUNTRYshopper_information.country is not COL.
400SHOPPER_INVALID_IDTYPEtype_doc_identi is not one of the document types accepted in Colombia.
400SHOPPER_INVALID_IDNum_doc_identi length does not match the document type.
400SHOPPER_INVALID_EMAILemail fails validation.
400SHOPPERINFO_INVALIDshopper_information is missing required keys.
400EMPTY_FIELDA required shopper_information field is empty.

OpenPay API errors are surfaced in the operation logs using description, error_code and request_id from the upstream JSON.


Updated 2 months ago

Did this page help you?

Updated 2 months ago

Did this page help you?