Create a Card on File Transaction

PagSeguro enables you to save a customer's credit card information for future purchases and then using that stored information to process subsequent payments. This feature is called Card on File.

What is Card on File?

Card on File allows you to securely store a customer's credit card details after an initial transaction. The information is stored in PagSeguro server, eliminating the securities concerns from your side.

When you store a card, you receive a unique token that represents the card's information. The token you will receive is the UUID of the payin-card entry. You can then use this token for future payments without requiring the customer to re-enter their card details.

The core benefits of this feature include:

• Enables one-click purchases for returning customers.
• Automates the billing for subscriptions and recurring services.

When to Use Card on File

You should use the Card on File feature for two primary scenarios:

• One-Click Payments: A customer makes a purchase and agrees to save their card for future use. When they return to your site, they can select the saved card to pay instantly, without needing to re-enter their full card details. This is common in e-commerce stores to improve the user experience for repeat customers.

• Subscription or Recurring Billing: A customer signs up for a service that requires regular payments (e.g., monthly or yearly). You store their card during the initial sign-up and then use the token to automatically charge them for each billing cycle without any further action from the customer.

The Card on File Lifecycle

A Card on File token has a simple lifecycle with two possible states:

A token's status becomes ACTIVE only after the initial payment authorization is successful. If a subsequent payment attempt fails for a mapped reason (like the card expiring), the token's status will change to INACTIVE.

Card on File Transaction Flow

This flow covers two main scenarios, the initial transaction where the card is stored and a subsequent transaction that uses the stored card token.

1. Customer → Merchant: The customer completes a purchase on the merchant's website and agrees to save their card for future use.
2. Merchant → PagSeguro: The merchant server submits the transaction details, including the store = true parameter, to instruct PagSeguro to save the card.
3. PagSeguro → Merchant: PagSeguro processes the initial payment, securely stores the card details, and returns the transaction status along with a unique Card on File token.
4. Merchant -> Customer: Confirms the payment.
5. Customer → Merchant: The customer returns to make a subsequent purchase (e.g., a one-click buy) or a scheduled subscription payment is due.
6. Merchant → PagSeguro: The merchant server submits a new transaction request using the stored token and specifying who initiated the payment (initiatedBy).
7. PagSeguro → Merchant: PagSeguro processes the payment using the stored card details and returns the new transaction status.
8. Merchant → Customer: The merchant server communicates the final transaction status to the customer.

Initiate a Transaction (CIT/MIT)

For transactions using stored cards, it's important to indicate who initiated the payment. This is done using the initiatedBy parameter. This information is crucial for payment processing and risk analysis. The two options available are CIT and MIT:

• Customer-Initiated Transaction (CIT): This occurs when the customer is actively participating in the transaction. You should set initiatedBy to CUSTOMER when creating the payment in these situations.

  • The very first transaction where the card is saved is always a CIT.
  • A "one-click buy" where the customer logs in and clicks "Pay Now" using their saved card is also a CIT.

• Merchant-Initiated Transaction (MIT): This occurs when you, the merchant, process a payment automatically without the customer's direct involvement at the time of the charge. You should set initiatedBy to MERCHANT when creating the payment in this scenario.

  • An automated monthly subscription charge is a classic example of an MIT.

The API response will return this information when after you create the payment. The API will return CIT or MIT in the recurrence.type field based on the information you shared when creating the payment.

Create a Payment and Get a Token

You can only generate a Card on File token during a payment transaction. There is no separate endpoint for creating a token without processing a charge, you need to use the Create a Transaction endpoint.

To generate the Card on File token, you have to add the store = true when creating the payment with the Create a Transaction endpoint. This instructs the system to save the card details and generate a token upon successful payment authorization. You can see an example below:

{
    "integration": {
        "reference": "REF-XXX-1234567890",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "language": "pt_BR"
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
            }
        ]
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "raw": {
                "number":"4073020000000002",
                "cvc":"123",
                "expiration_month":"12",
                "expiration_year":"2028"
            },
          	"holder_name": "jonh doe",
						"store": true
        }
    },
    "payer": {
        "email": "[email protected]",
        "ip": "192.0.2.146",
        "person": {
            "name": "Mr. Payer Full Name",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "98765432101"
            },            
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}

Handling the Response

If the payment is authorized successfully, the API response will include a credit_card object containing the new Card on File token in the id field. You must store this ID on your server and associate it with your customer for future use.

{
  "code": "25a58ef1-3755-476b-b2f6-e445b170a849",
  "reference": "REF-XXX-1234567890",
  "status": "PENDING",
  "amount": 101.1,
  "currency": "BRL",
  "country": "BR",
  "charge": {
    "type": "CREDIT_CARD",
    "method": "MASTERCARD",
    "credit_card": {
      "last_four": 1234,
      "bin": 123546,
      "expiration_date": "YYYY-MM",
      "id": "41122c49-0099-447d-8d20-fd5f4cb38050"
    },
    "recurrence": {
      "created_at": "2021-06-01T14:52:08Z",
      "initial_request_id": "41122c49-0099-447d-8d20-fd5f4cb38050",
      "type": "CIT"
    }
  }
}

📘

ID Format

The token ID is a UUID with hyphens (e.g., 3e233f49-04d0-40ee-ae13-984e2b7988a4). Unlike some other platform IDs, it does not include a prefix like CARD_.

Create Payments Using the Token

Once you have a valid and ACTIVE Card on token, you can use it to process new payments.

To create a payment using the Card on File token, you will use the Create a Transaction endpoint. In the credit_card object, you have to inform the stored token in the id field and the card cvv. You also need to defined who initiated the transaction by setting the initiatedBy parameter to MERCHANT or CUSTOMER based on the scenario.

📘

CVV

The cvc parameter is optional and depends on your merchant configuration. By default, it is mandatory. If your configuration allows it and you do not send the cvv, the system will attempt a payment without it. This requires the payment processor to support CVV-less transactions.

You can see an example of a request below:

{
   "integration":{
      "reference":"REF-XXX-1234567890",
      "notification_url":"https://www.merchantwebsite.com/notify?type=transaction",
      "language":"pt_BR"
   },
   "order":{
      "currency":"BRL",
      "items":[
         {
            "quantity":1,
            "description":"Product description",
            "unit_price":101.10
         }
      ]
   },
   "charge":{
      "country":"BR",
      "type":"CREDIT_CARD",
      "initiatedBy":"MIT",
      "credit_card":{
         "id":"7e18637f-f3ee-4ce2-adaf-05c5ceae3833",
         "cvc":"123"
      }
   },
   "payer":{
      "email":"[email protected]",
      "ip":"192.0.2.146",
      "person":{
         "name":"Mr. Payer Full Name",
         "birth_date":"1970-01-01",
         "document":{
            "type":"CPF",
            "number":"98765432101"
         },
         "phone":{
            "country_code":"55",
            "number":"44900000000"
         }
      }
   }
}

Upon a successful request, the API returns transaction details. Example response:

{
    "code": "25a58ef1-3755-476b-b2f6-e445b170a849",
    "reference": "REF-XXX-1234567890",
    "status": "PENDING",
    "amount": 101.1,
    "currency": "BRL",
    "country": "BR",
    "created_at": "2021-04-12T12:43:13Z"
}

Validation and Error Handling

The API performs checks before processing a payment with a token:

• It verifies that the token belongs to the requesting merchant.
• It checks that the token's status is ACTIVE.

If either of these checks fails, the API will return a 422 error with the following message:

{
  "error": "card_on_file_status_does_not_allows_processing_or_not_found"
}