Token Credit Card Payment

Tokenization is a process that replaces sensitive credit card data with a unique token. This technique allows merchants to securely store and reuse customer payment information for future transactions, enabling features such as one-click buying, retrying transactions, and recurring payments.

❗️
Important Notes

Tokenization is available only for credit card payments.

The credit card code can only be used after the transaction's status is COMPLETE.

The credit card code is tied to the customer email it was generated for and cannot be reused with a different email.

Duplicate tokenization attempts for the same card and customer email will result in the payment method object not being returned.

Token Credit Card Payment Flow

Merchant: Save and store payment method.
Customer → Merchant: Fill and submit additional payment info.
Merchant → PagSeguro: Submit data to the Create a payment endpoint.
PagSeguro → Merchant: Create order and return transaction status and ID.
Merchant → Customer: Return transaction status to the customer.

Follow the steps below to create a token credit card payment:

Step 1: Saving the Payment Method

To save a payment method, you must create a payment request with the charge[].payment-info.save parameter set to true. The payment can be either a Raw Credit Card Payment or an Encrypted Credit Card Payment. This will initiate the tokenization process.

🚧
Conclude Initial Transaction
Ensure that the transaction status is COMPLETE before using the credit card token for future transactions.

Below is an example request and response:

{
  "transaction": {
    "reference": "REF-XXX-1234567890",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "credit-card",
        "sub-type": "mastercard"
      },
      "payment-info": {
        "installments": 3,
        "token": "eyJkbmEiOiI2NzY3YzAxNDEzNGM0NTc4ODg0ZjU2MjdmYTI0ZGVhZiIsImlwIjoiMjAwLjIyMS4xMzAuNDkiLCJkZiI6ImNmYWI3MDcxMDJlZDQ4MjU4MzJhNmY2MDBhNWZjZjc2In0=",
        "save": true
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 0",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

{
  "transaction": {
    "code": "99481144",
    "reference": "REF-XXX-1234567890",
    "amount": 100,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T15:16:31.76093422-03:00"
  },
  "payment-methods": [
    {
      "code": "5B990EBB79F54E65B752EC555BD3A9B6",
      "credit-card": {
        "brand": "mastercard",
        "masked-number": "************5099",
        "expiration-date": "2021-12"
      },
      "date-created": "2018-10-09T15:16:32.508735399-03:00"
    }
  ]
}

Step 2: Storing the Payment Method

Once the payment method is saved, you should store the payment-methods object for future use. This stored token can then be used to make future transactions once the original transaction's status is COMPLETE.

{
  "code": "5B990EBB79F54E65B752EC555BD3A9B6",
  "credit-card": {
    "brand": "mastercard",
    "masked-number": "************5099",
    "expiration-date": "2021-12"
  },
  "date-created": "2018-10-09T15:16:32.508735399-03:00"
}

Step 3: Using the Saved Payment Method

Once the original transaction status has changed to COMPLETE, you can use the stored token to make a credit card payment request by sending it and the other needed information to the Create a payment endpoint. The token goes under the payment-info, in the code parameter.

{
  "transaction": {
    "reference": "REF-XXX-1234567891",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "credit-card",
        "sub-type": "mastercard"
      },
      "payment-info": {
        "installments": 3,
        "code": "5B990EBB79F54E65B752EC555BD3A9B6"
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro dos testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

📘
Reason Codes
If the request fails, the API will return an HTTP status code other than 200. The response body will include an errors array with descriptive messages and corresponding error codes.
For the full list of possible error codes, see the Reason Codes reference.

Token Credit Card Payment

❗️
Important Notes