Skip to main content

Payment Sources & Tokenization

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.

With Wompi you can charge your customers more than once by using by using payment sources. For example you can build subscription services for a magazine, charge for an on-demand service like a delivery or whichever payment experience in which your users need to pay more than once, but giving you the credit card details only once.

The payment sources feature can be used with Cards or Nequi accounts, which requires the customer to only input the Card or Nequi information once, so that it can be used to charge them afterwards, without requiring their presence or manual intervention again.

You only need to follow the step by step instructions which are detailed next:

Guide for intermediate - advanced users
The steps outlined next require an integration with and direct usage of our API, which is why they are orientes to intermediate and advances developers who are familizared with the usage of APIs.

Step by step

  • Step 1 — Ask users for the payment method information.
  • Step 2 — Create a payment source.
  • Step 3 — Create a transaction using the payment source.

Step 1: Ask for the payment method information

The first of these 3 steps to charge using a payment source, requires the secure storage of a credit card or Nequi account information. For that you will use our API in a way to save information in a safe and secure way.

Never store sensitive information!
We strongly recommend that you never store sensitive information like credit card numbers, nequi accounts, or payment method details, since you are putting your customers data at risk and exposing yourself to legal problems and sanctions depending on the regulation in your country. Wompi has the highest safety standards in the industry regarding storage and encryption in a 100% secure way.

The process of saving and representing card information in a secure way is called: tokenization. This means that you should send the payment method information to the Wompi API only once, to obtain a token which you will use to create a payment source as outlined in Step 2 of this guide.

Take into account the API environment

Remember that in Wompi there is a Sandbox environment for test transactions and a Production environment for real payments. For more details read our guide on environments and sources.clicking here.

Cards

For cards (credit and debit with CVV) the endpoint that you should use is /v1/tokens/cards, sending a POST with the following JSON body:

{
"number": "4242424242424242", // Card number (string, with no spaces or special chars)
"exp_month": "06", // Expiration month (2-digit string)
"exp_year": "29", // Año de expiración (2-digit string)
"cvc": "123", // Security code (3 or 4 digit string)
"card_holder": "Pedro Pérez" // Cardholder name (string, 5 chars minimum length)
}

As a result of this request, you'll get the following response:

{
"status": "CREATED",
"data": {
"id": "tok_prod_15_44c5638281if67l04eA63f705bfA5bde",
"created_at": "2020-09-07T19:09:31.585+00:00",
"brand": "VISA",
"name": "VISA-4242",
"last_four": "4242",
"bin": "538696",
"exp_year": "06",
"exp_month": "29",
"card_holder": "Pedro Pérez",
"expires_at": "2021-09-05T19:09:30.000Z"
}
}

If the status key has the "CREATED" value, this means the cards has been correctly tokenized. You can now use its token value ("tok_prod_15_44c5638281if67l04eA63f705bfA5bde"), in the id key to create a payment source.

Nequi accounts

For payments with Nequi, the endpoint that you should use is /v1/tokens/nequi sending a POST with the public key as an authorizer with the following JSON body:

{
"phone_number": "3017654321"
}

In the following response, the id key contains the new Nequi Token ("nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5"), which you can use to create a payment source. However, the customer still needs to accept the subscription on his cellphone, so that the status changes from "PENDING" to "APPROVED".

{
"data": {
"id": "nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"status": "PENDING",
"phone_number": "3107654321",
"name": "Company Name"
}
}

To check the state of the subscription, you can use the GET /v1/tokens/nequi/:nequi_token endpoint with the aforementioned Nequi Token:

GET /v1/tokens/nequi/nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5

Once you get an APPROVED string in the "status" property, it will be possible to properly create the payment source.

{
"data": {
"id":"nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"status":"APPROVED",
"phone_number":"3107654321",
"name":"Company Name"
}
}

Step 2: Create a payment source

Use your private key to create Payment Sources
Take into account that in this case, the endpoint for creating payment sources requires the use of your private key, which must be sent from your back-end (server), in order to keep it safe. Never do it from a user's device (browser, mobile phone, etc)

To create a payment source you'll use the following endpoint:

POST /v1/payment_sources

With the following required fields:

  • "customer_email" is the end user's email address
  • "type" indicates the kind of payment method that corresponds to the token, which can be "CARD" or "NEQUI".
  • "token" Nequi or Card token obtained above
  • "acceptance_token" an acceptance-token

Cards

The following is the request body you'll need to send when creating Payment Sources for a Card, using "CARD" as its type and the card token obtained from Step 1:

{
"type": "CARD",
"token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301",
"customer_email": "john_smith@example.com",
"acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s"
}

You should now obtain a JSON response similar to the following, indicating the payment source was created and is available to use:

{
"data": {
"id": 3891,
"public_data": {
"type": "CARD"
},
"type": "CARD",
"status": "AVAILABLE"
}
}

Nequi

The following is the request body you'll need to send when creating Payment Sources for Nequi, using "NEQUI" as its type and the Nequi token obtained from Step 1:

{
"type": "NEQUI",
"token": "nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"customer_email": "john_smith@example.com",
"acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s"
}

You will then obtain a response indicating that the payment source was successfully created, with a structure like the following:

{
"data": {
"id": 3891,
"public_data": {
"type": "NEQUI",
"phone_number": "3105671703"
},
"type": "NEQUI",
"status": "AVAILABLE"
}
}

Step 3: Create a transaction

You can charge your customers using the id of a payment source, without asking them to intervene every time in the process. This way you can for example charge for a periodical or on-demand service.

For this, you need to use the same transaction endpoint that one time payments use (POST to /v1/transactions), with the difference that this time you will send the information for the payment method directly (object payment_method) with the number of installments if the payment method represented by the payment source is a card. In either case you will need to add the payment_source_id you just created, for example:

{
"amount_in_cents": 4990000, // Amount in cents
"currency": "COP", // Currency
"signature": "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5", //Integrity signature
"customer_email": "example@gmail.com", // User email
"payment_method": {
"installments": 2 // Number of installment if the payment source represents a card otherwise ignore the payment_method field altogether.
},
"reference": "sJK4489dDjkd390ds02", // Unique payment reference
"payment_source_id": 3891 // Payment source ID
}

NOTE: If you have doubts about how to generate the integrity signature value you can review the following documentation: Generate an integrity signature.

Widget in tokenization mode

You can integrate our Widget in tokenization mode so that you can save your users' information more quickly and safely.

With just a few lines of HTML:

    <form method="POST" action="/process_token">
<script
src="https://checkout.wompi.co/widget.js"
data-render="button"
data-widget-operation="tokenize"
data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
>
</script>
</form>

With the token inside the response you must do a POST to /v1/payment_sources from your server and using your private merchant key. Remember never to use the private key in insecure contexts like your HTML code.