Payment Methods

Important changes 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 available payment methods are:

• Credit or Debit Cards: Allows your customers to pay using credit or debit cards.
• Clave: Offer your customers the possibility to use their Key card to complete the payment

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

1. Specify the payment_method field with a JSON object containing specific details for each method, described 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 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 of a transaction can be: APPROVED (approved) , DECLINED (declined), VOIDED (anulled, applies to transactions with card only) 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 or Mastercard 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:

1. You must first tokenize a card (more details below).
2. You must ask the end how many installments does he wants to make his payment.

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 businesses 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 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 use 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 later on 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

After obtaining the token details and having asked the user the number of ("installments"). The payment method fields for a new transaction with a card should be similar to the following:

{
  "payment_method": {
    "type": "CARD",
    "installments": 1, // 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.

Clave

We will guide you through the process of using the Clave payment method in our API. Clave is a card system belonging to the company Telered in Panama, offering your customers a secure way to process payments on your platform.

Create transaction

To get started with the Clave payment method, you need to create a new transaction using the endpoint POST /v1/transactions. Make sure to include the following specific fields for the Clave payment method:

{
  "payment_method": {
    "type": "CLAVE"
  },
  // Other transaction fields...
  "amount_in_cents": 2000,
  "currency": "USD",
  "customer_email": "{{EMAIL}}",
  "reference": "{{REFERENCE}}",
  "acceptance_token" : "{{ACCEPTANCE_TOKEN}}"
}

Check transaction

After creating the transaction, it's essential to periodically check for changes in the transaction using the Wompi API and the transaction ID. You can do this by using the endpoint GET /v1/transactions/<TRANSACTION_ID>.

Once you receive the response, you should validate the data->payment_method->extra->clave_auth->url field. This URL should be loaded into an <iframe> element within your payment page. Here, your customers will interact with the Clave system to continue the transaction process. Upon successfully completing the process, the data->status field will change to APPROVED, DECLINED, or ERROR, depending on the outcome.

Below is an example of the response structure:

{
    "data": {
        "id": "1156-1689191638-98479",
        "created_at": "2023-07-12T19:53:58.190Z",
        "amount_in_cents": 1000,
        "reference": "refence_test1",
        "currency": "USD",
        "payment_method_type": "CLAVE",
        "payment_method": {
            "type": "CLAVE",
            "extra": {
                "clave_auth": {
                    "url": "URL_TEST",
                    "session_id": "12345",
                    "client_session_id": "12345"
                }
            }
        },
        "redirect_url": null,
        "status": "PENDING",
        "status_message": null,
        "merchant": {
            "name": "Comercio De Prueba",
            "legal_name": "Comercio De Prueba",
            "contact_name": "Pepito Perez",
            "phone_number": "+507123456789",
            "logo_url": null,
            "legal_id_type": "RUC",
            "email": "test@wompi.com",
            "legal_id": "123456789-1"
        },
        "taxes": []
    },
    "meta": {}
}