Payment Methods
Every time you create a transaction using our API, you have the option of processing the payment using different payment methods. Currently the following payment methods are available:
- Credit or Debit Cards: Allows your customers to pay using credit or debit cards.
- Bancolombia Transfer Button: Allows your customers to pay using their savings or checking account from Bancolombia.
- Nequi: Allows your customers to pay with Nequi using their cellphone to complete the payment.
- PSE: Allows your customers to pay with PSE using the savings or checking account from any Colombian bank.
- Cash Payment in Corresponsal Bancario Bancolombia: Allows your customers to pay with cash in any of the more than 15,000 physical points of payment from Bancolombia called Corresponsales Bancarios Bancolombia.
- PCOL: Allow your customer to pay points redemption from Puntos Colombia loyalty program.
To use a payment method you must POST
to the /transactions
endpoint with:
- Specify the field
payment_method_type
and specify one of these 3 values:CARD
,NEQUI
orPSE
- Specify the field
payment_method
with a JSON object that contains more specific details with each of the methods outlined below.
To end the payment process for any of the available payment methods, we recommend periodically verifying (long polling) the state of a transaction, waiting a for a final status
(approved, denied, voided or error), using the transaction ID and our API, since none of the payment methods deliver an instant synchronous response). A transaction that has just been created always has a PENDING
status.
Final statuses for a transaction
The final status
for a transaction can be: APPROVED
, DECLINED
, VOIDED
or ERROR
(if there is an external error with a payment method during the transaction).
Credit or Debit Cards
In Wompi your customers can process payments using a Visa, Mastercard or Amex Credit or Debit Card, as long as the card has a CVC (card verification code), usually printed on the back of the card.
The payment method type that you must use to create the transaction is CARD
. When using the payment method CARD
you need to take into account that:
- You must first tokenize a card. (more details below)
- You need to ask the end user how many installments does he want his payment deferred to.
Tokenize a Credit or Debit Card
To securely tokenize a credit or debit card, you must use the endpoint (using your public key on the authentication header):
POST /v1/tokens/cards
To this endpoint, you must send the following card information inside the the request body:
{
"number": "4242424242424242", // Card number (13 to 19 digits)
"cvc": "123", // Card verification code (3 or 4 digits, depending on franchise)
"exp_month": "08", // Expiration month (2 digits string)
"exp_year": "28", // Expiration year (2 digits string)
"card_holder": "John Smith" // Card holder name
}
The endpoint will respond something like the following:
{
"status": "CREATED",
"data": {
"id": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301", // TOKEN you must when creating the transaction
"created_at": "2020-01-02T18:52:35.850+00:00",
"brand": "VISA",
"name": "VISA-4242",
"last_four": "4242",
"bin": "424242",
"exp_year": "28",
"exp_month": "08",
"card_holder": "John Smith",
"expires_at": "2020-06-30T18:52:35.000Z"
}
}
In this response, the value of the "id"
field is the token you must use inside the "payment_method"
object (in this case "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301"
), to further create a transaction.
Create the Transaction
Taking into account these detailsand having asked the end user the number installments, the payment method fields for a new transaction with a card should be similar to the following:
{
"payment_method": {
"type": "CARD",
"installments": 2, // Number of installments
"token": "tok_prod_e6S2sAz383mdCQ38dj32z" // Card token
}
// Other transaction fields...
}
Lastly, remember to periodically check the state of the transaction in Wompi from your system, using the transaction ID and our API endpoint GET /v1/transactions/:id
.
Bancolombia Transfer Button
With Wompi your customers can complete a payment using their Bancolombia savings or checking account. The name of the payment method that you should use to create the transaction is BANCOLOMBIA_TRANSFER
.
When using the BANCOLOMBIA_TRANSFER
payment method, you need to take into account the following steps:
- Your customer must specify the legal type of person. Currently, the only available option is
PERSON
- You should specify a payment description in a maximum of 64 characters.
- If you're using the Sandbox environment, you must send the
sandbox_status
field, specifying the final status you wish to simulate. It should be one of the following values:APPROVED
,DECLINED
orERROR
.
The payment method fields for a BANCOLOMBIA_TRANSFER transaction will look like the following:
{
"payment_method": {
"type": "BANCOLOMBIA_TRANSFER",
"user_type": "PERSON", // Legal type of the person
"payment_description": "Payment to Wompi Store", // Payment description
// The next field is ONLY required if you're using the Sandbox environment:
"sandbox_status": "APPROVED" // Desired final status. One of the following: APPROVED, DECLINED o ERROR
}
// Other transaction fields...
}
When creating a transaction, you must check it continually using a long polling until it contains a field called async_payment_url
in an obect extra
, within payment_method
. Once you have it, you need to redirect the customer to this URL so that he can comokete the payment in the respective financial institution. The field you need to check for will look like the following:
{
"payment_method": {
// Other payment method fields
"extra": {
"async_payment_url": "https://..." // URL where user should be redirected to compelted the payment
}
}
// Other transaction fields...
}
After finalizing the payment process through BANCOLOMBIA_TRANSFER
, it will redirect the customer to the redirect_url
which you specified in the transaction (if you did), so that you can verify the result of the transaction again using long polling, until you get a final status
.
Lastly, remember to periodically check the state of the transaction in Wompi from your system using the transaction ID and our API endpoint GET /v1/transactions/<TRANSACTION_ID>
.
Bancolombia QR
Allow your customers to use their Bancolombia accounts and Nequi accounts by generating a QR that must be read by the respective bank app. The name of the payment method that you must use when creating the transaction is BANCOLOMBIA_QR
. You must bear in mind that payments through this medium only apply to natural persons.
The payment method fields for a BANCOLOMBIA_QR transaction will look like the following:
{
"payment_method": {
"type": "BANCOLOMBIA_QR",
"payment_description": "Payment to Wompi Store", // Payment description
// The next field is ONLY required if you're using the Sandbox environment:
"sandbox_status": "APPROVED" // Desired final status. One of the following: APPROVED, DECLINED o ERROR
}
// Other transaction fields...
}
When creating the transaction, you must consult it continuously (long polling) until it contains a field called qr_image
and qr_id
, which will be inside the payment_method
property, which will have the image of the QR in base64
inside an extra
object.
Once you get it, you can render the QR in an img
tag as follows:
<img src="data:image/svg+xml;base64 + ${qr_image}"/>
The field you need to check for will look like the following:
{
"payment_method": {
"type": "BANCOLOMBIA_QR",
// Other payment method fields
"extra": {
"qr_id": "a3827b90-501b-11ed-ae9b-3156df51ed75", // ID QR code
"qr_image": "PD94bWwgdmVyc2lvbj0iK.....", // Qr image code in base64
"external_identifier": "d00000000000" //Reconciliation ID once the payment is made
}
}
// Others transactions fields...
}
After finalizing the payment process through BANCOLOMBIA_QR
, it will redirect the customer to the redirect_url
which you specified in the transaction (if you did), so that you can verify the result of the transaction again using long polling, until you get a final status
.
Lastly, remember to periodically check the state of the transaction in Wompi from your system using the transaction ID and our API endpoint GET /v1/transactions/<TRANSACTION_ID>
.
Nequi
With Wompi your customers can complete a payment by using Nequi on their cellphones. The name of the payment method that you need to use to create the transaction is NEQUI
.
By using the payment method NEQUI
you only need to ask your customer for a 10 digit colombian cellphone number that is registered with Nequi, to send it along with the information to our API. Remember to tell your customer that he must have le Nequi app installed on his phone to complete the payment using this method.
Once you have the customer's cellphone number, all the fields should look like the following example:
{
"payment_method": {
"type": "NEQUI"
"phone_number": "3107654321" // Nequi cellphone number
}
// Other transaction fields...
}
When creating a transaction, you should indicate your customers that they will get a push notification from Nequi on their cellphones, in which they need to accept or reject the transaction. This results will be reflected in Wompi in a matter of seconds, once the user has taken action.
Lastly, remember to periodically check the state of the transaction in Wompi from your system using the transaction ID and our API endpoint GET /transactions/:id
.
PSE
With Wompi your customers can complete a payment using their debit or checking bank accounts, for any Colombian bank, using PSE. The name of the payment method that you should use to create the transaction is PSE
.
When using the PSE
payment method, you need to take into account the following steps:
- You need to obtain a list of financial institutions using the API endpoint
GET /v1/pse/financial_institutions
- Your customer much choose the financial institution (bank) which he wants to pay with.
- Your customer must specify the legal type of person that he is: a natural (
0
) or business (1
) person. - Your customer must specify his legal Colombian ID Type and Number. All residents and foreigners in Colombia have one of these ID's.
- You should specify the name of what you are paying in a maximum of 30 characters.
After your clients have choosen a financial institurion, use his (code
) as the identifier which you will send to create the transaction. That way the payment method fields for a PSE transaction will look like the following:
{
"payment_method": {
"type": "PSE",
"user_type": 0, // Person type, natural (0) or business (1)
"user_legal_id_type": "CC", // Document type, CC, CE or NIT
"user_legal_id": "1099888777", // Document number
"financial_institution_code": "1", // Financial institution code
"payment_description": "Payment to Wompi Store" // Payment description
}
// Other transaction fields...
}
When creating a transaction, you must check it continually using long polling until it contains a field called async_payment_url
in an obect extra
, within payment_method
. Once you have it, you need to redirect the customer to this URL so that he can comokete the payment in the respective financial institution. The field you need to check for will look like the following:
{
"payment_method": {
// Other payment method fields
"extra": {
"async_payment_url": "https://..." // URL where user should be redirected to compelted the payment
}
}
// Other transaction fields...
}
After finalizing the payment process through PSE
, it will redirect the customer to the redirect_url
which you specified in the transaction (if you did), so that you can verify the result of the transaction again using long polling, until you get a final status
.
Lastly, remember to periodically check the state of the transaction in Wompi from your system using the transaction ID and our API endpoint GET /v1/transactions/<TRANSACTION_ID>
.
Cash Payment in Corresponsal Bancario Bancolombia
This payment method allows your customer to make cash paymentx by going to any Bancolombia branch office. To create a cash payment intention you need to follow these steps:
Step 1: Create transaction
You must create a transaction assigning the value BANCOLOMBIA_COLLECT
to the type
field of the payment_method
object.
{
"payment_method": {
"type": "BANCOLOMBIA_COLLECT" // Cash referenced Bancolombia payment
}
// Other transaction fields...
}
You will receive a transaction where the status
field will have a PENDING
value.
Step 2: Query the transaction
After creating the transaction you must query it through GET /v1/transactions/<ID_DE_TRANSACCION>
by long polling until you get the business agreement data that will be presented to you in the payment_method
object in the extra
field as follows:
{
"payment_method": {
"type": "BANCOLOMBIA_COLLECT",
"extra": {
"business_agreement_code": "12345", // This is an example
"payment_intention_identifier": "65770204276" // This is an example
}
// Other transaction information...
}
Step 3: Share the payment information
Once you have the payment information from the previous step, you can share the business_agreement_code
and payment_intention_identifier
with your customers so they can personally make the payment at any Corresponsal Bancario Bancolombia physical points of payment.
PCOL
With Wompi your customers can complete a payment using their points from "Puntos Colombia". There are two options (i) Total payment with points (ii) Part of the payment with Points + a Second payment method that includes Tarjetas de Crédito o Débito, Botón de Transferencia Bancolombia, Nequi o PSE
. The name of the payment method that you should use to create the transaction is PCOL
.
Step 1: Create PCOL transaction
You must create a transaction assigning the value PCOL
to the payment_method
object.
{
"customer_email": "myemail@mail.com",
"customer_data": {
"phone_number": "+573121111111",
"full_name": "Nombre Apellido"
},
"payment_method": {
"type": "PCOL"
}
// Other transaction information...
}
When creating a transaction, you must check it continually using long polling until it contains a field called async_payment_url
in an obect extra
, within payment_method
. Once you have it, you need to redirect the customer to this URL so that he can start the the payment with points redemption. The field you need to check for will look like the following:
{
"payment_method": {
// Other payment_method fields
"extra": {
"async_payment_url": "https://..." // URL where user should be redirected to compelted the payment
}
}
// Other transaction information...
}
Step 2: Query PCOL transaction (Points redemption result)
At the end of the redemption process, your customer will be redirect to the redirect_url
that you originally specified in the transaction, so that you can verify the result of the redemption, and identify if the total payment was make with points or partial and has a remaining amount to pay.
Upon receiving the redirection, a long polling of the transaction must be done again until the status
field is different from PENDING and receving the fields point_redeemed
, redeemed_amount_in_cents_pcol
and remaining_amount_in_cents
within an object extra
, which will be inside the payment_method
property:
{
"payment_method": {
"type": "PCOL",
"extra": {
"points_redeemed": 1000, // Points redeemed
"remaining_amount_in_cents": 0, // Remaining amount to pay with another payment method
"redeemed_amount_in_cents_pcol": 700000, // Amount redeemed using points
}
},
"status": "APPROVED",
// Other transaction information...
}
You should check the value within the field remaining_amount_in_cents
:
(i) If the value is 0, and transaction status APPROVED this means that the customer paid the transaction total amount with points.
(ii) If the value is 0, and the status of the transaction is ERROR or DECLINED, this will indicate that any points were redeemed; in this case you can enable the customer the option to pay the total transaction with a second payment method. (Step 3)
(iii) If the value is greater than 0, you must enable the option to pay with a second payment method the reamining amount. (Step 3)
Step 3: Second payment method
If the previous step results in (ii) or (iii) a second payment methos selection must be enabled with the options Tarjetas de Crédito o Débito, Botón de Transferencia Bancolombia, Nequi and PSE
to pay the value in remaining_amount_in_cents
. Once selected the second payment method, a second transaction must be created. In this case you should follow the documentation of the payment method and include a new field to associate the first transaction (parent_transaction_id
):
Card as second payment method
{
"payment_method": {
"type": "CARD",
"installments": 2, // Número de cuotas
"token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301" // Token de la tarjeta de crédito
},
"parent_transaction_id": "1929-1666902167-47609" // PCOL transaction
// Other transaction information...
}
Botón Transferencia Bancolombia as second payment method
{
"payment_method": {
"type": "BANCOLOMBIA_TRANSFER",
"user_type": "PERSON",
"payment_description": "Pago a Tienda Wompi",
"ecommerce_url": "https://comercio.co/thankyou_page"
},
"parent_transaction_id": "1929-1666902167-47609" // PCOL transaction
// Other transaction information...
}
Nequi as as second payment method
{
"payment_method": {
"type": "NEQUI"
"phone_number": "3107654321"
},
"parent_transaction_id": "1929-1666902167-47609" // PCOL Transaction
// Other transaction information...
}
PSE as second payment method
{
"payment_method": {
"type": "PSE",
"user_type": 0,
"user_legal_id_type": "CC",
"user_legal_id": "1099888777",
"financial_institution_code": "1",
"payment_description": "Pago a Tienda Wompi, ref: JD38USJW2XPLQA",
"ecommerce_url": "https://comercio.co/thankyou_page"
},
"parent_transaction_id": "1929-1666902167-47609" // PCOL transaction
// Other transaction information...
}
Lastly, remember to periodically check the state of the transacion in Wompi from your system using the transaction ID and our API endpoint GET /transactions/:id
. When checking a PCOL transaction with second payment method associated, you will get a field called child_transaction_id
witing the extra
object, within the property payment_method
; this field is the transaction id for the second payment method.
{
"payment_method": {
"type": "PCOL",
"extra": {
"points_redeemed": 0,
"async_payment_url": "https://....",
"external_identifier": "external-id-123",
"remaining_amount_in_cents": 300000,
"redeemed_amount_in_cents_pcol": 0,
"child_transaction_id": "11463-1666651097-12919" // Transacción segundo medio de pago
}
}
}
In the same way, when checking for the child_transaction_id
you will get the PCOL transaction id within parent_transaction_id
:
{
"payment_method": {
"type": "NEQUI", // Second payment method
"phone_number": "3222222222",
"extra": {
"parent_transaction_id": "11463-1666649502-97081" // PCOL Transaction
}
}