Payment Methods · Wompi Docs

Important change on the Public API

When creating transactions and payment sources, and because we keep our users privacy in the top of our priorities, the usage of acceptance tokens is now mandatory when creating either of these resources through our API.

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.

To use a payment method you must POSTto the /transactions endpoint with:

Specify the field payment_method_type and specify one of these 3 values: CARD, NEQUIor PSE
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.

Never store card sensitive data!

We completely discourage the storage of card sensitive data on your end. Not only you risk your users' data, but you can face economic sanctions and legal problems. Wompi has a PCI DSS certification for securely handling, transmitting and processing card sensitive data, therefore preventing merchants from storing this data, by using only safely generated card tokens.

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.

Don't use a token more than once!

If you need to create multiple transactions for the same card, use our Payment Sources feature.

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 transacion 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 or ERROR.

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
  }
  // Otros campos de la transacción a crear...
}

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 reuslt of the transaction again using long polling, until you get a final status.

Lastly, remember to periodically check the state of the transacion 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 NEQUIyou 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 transacion 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 reuslt of the transaction again using long polling, until you get a final status.

Lastly, remember to periodically check the state of the transacion in Wompi from your system using the transaction ID and our API endpoint GET /v1/transactions/<TRANSACTION_ID>.