Documentation

Raw Credit Card Payment

Suggest Edits

To create a raw credit card payment, merchants must securely collect and transmit customer payment details, ensuring compliance with industry standards for security and privacy. This process involves sending raw credit card data to PagSeguro’s servers for processing, which is suitable only for merchants certified with PCI Level 1 or Level 2.

❗️

PCI-DSS Compliance

Merchants must adhere to PCI-DSS standards when using raw credit card data. This method should only be used if PCI certification is achieved.

Raw Credit Card Payment Flow

  1. Merchant → PagSeguro: Get installment options from PagSeguro's system (optional).
  2. Merchant → Customer: Dysplay available installment options (optional).
  3. Customer → Merchant: Fill and submit payment info.
  4. Merchant → PagSeguro: Submit raw data to the Create a payment endpoint.
  5. PagSeguro → Merchant: Create order and return transaction status and ID.
  6. Merchant → Customer: Return transaction status to the customer.

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

Step 1: Collecting Customer's Information

Before initiating the payment, you need to collect all necessary information from the customer. This includes basic details such as their name, email, birth date, contact information, and address. Make sure that all fields are correctly filled out to avoid any issues during the payment process.

🚧

Delivery Address

Payer address is required when the cart item type is physical.

If you are PCI Level 1 or Level 2 certified, you can send raw credit card data directly to PagSeguro's servers.

🚧

Data Validation

Ensure that the card details are validated before submission to prevent errors, such as incorrect card numbers, expiration dates, or CVVs.

To request a raw credit card payment, you must send the relevant data to the Create a payment endpoint. This should include data such as the amount to be paid, the number of installments, credit card data, and customer info.

Step 2 (Optional): Getting Credit Card Brand and Installments

Credit card installment options allow customers to divide payments into smaller amounts. Installments are available for credit card transactions in Brazil.

Installments Available in Brazil

Credit card installment options:

  • Visa, MasterCard, American Express, Elo, Diners, Hipercard: Up to 12 installments.

📘

Minimum Installment Amount

The minimum installment amount is 5 BRL.

Check Card's Brand and Installments

You can check the card's brand and available installment options through the same endpoint with the Get brand and installments endpoint. To use this endpoint, you'll need to send the card's first six digits, the country of payment, and the order's value and currency. Below is an example request and response:

curl -X GET \
    'https://api.boacompra.com/card?bin=123456&country=BR&amount=16.00&currency=BRL' \
    -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
    -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'

{
  "bin": {
    "number": 123456,
    "brand": "visa",
    "cvvSize": 3,
    "expirable": true,
    "validationAlgorithm": "LUHN",
    "installment": true
  },
  "installments": [
    {
      "quantity": 1,
      "totalAmount": 16,
      "installmentAmount": 16,
      "interestFree": true
    },
    {
      "quantity": 2,
      "totalAmount": 16.48,
      "installmentAmount": 8.24,
      "interestFree": false
    }
  ]
}

Check Card's Brand

To check only the card's brand, you can use the Check brand name endpoint. For this endpoint, you'll only need to send the card's first six digits. Below is an example request and response:

curl -X GET \
    'https://api.boacompra.com/card/bin/123456' \
    -H 'content-type: application/json' \
    -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
    -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'

{
    "bin": {
        "number": 123456,
        "brand": "visa",
        "cvvSize": 3,
        "expirable": true,
        "validationAlgorithm": "LUHN",
        "installment": true
    }
}

Check Available Installments

To check the available installment options for a specific card, use the Check installment options endpoint. To use this endpoint, you'll need to send the card's brand, the country of payment, and the order's value and currency. Below is an example request and response:

curl -X GET \
    'https://api.boacompra.com/card/installments?brand=visa&country=BR&amount=16.00&currency=BRL' \
    -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
    -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'

{
  "installments": [
    {
      "quantity": 1,
      "totalAmount": 16,
      "installmentAmount": 16,
      "interestFree": true
    },
    {
      "quantity": 2,
      "totalAmount": 16.48,
      "installmentAmount": 8.24,
      "interestFree": false
    }
  ]
}

Step 3: Requesting a Credit Card Payment

To create a raw credit card transaction, you will send the credit card data and installment options to the Create a payment endpoint.

📘

Minimum Transaction Amount

The minimum transaction amount is 0.20 BRL.

Below is an example request and response:

curl -X POST \
  'https://api.boacompra.com/transactions' \
  -H 'accept: application/vnd.boacompra.com.v2+json; charset=UTF-8' \
  -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165' \
  -H 'content-type: application/json' \
  -d '{
     "transaction":{
        "reference":"REF-RAW-CC-1539193167",
        "project-number":1,
        "country":"BR",
        "currency":"BRL",
        "checkout-type":"direct",
        "notification-url":"https://billing.checkout.com/processing",
        "language":"pt-BR"
     },
     "charge":[
        {
           "amount":50.00,
           "payment-method":{
              "type":"credit-card"
           },
           "payment-info":{
              "installments":2,
              "credit-card":{
                 "number":"4073020000000002",
                 "cvv":"123",
                 "expiration-date":"2020-12"
              }
           }
        }
     ],
     "payer":{
        "name":"John Doe",
        "email":"[email protected]",
        "ip":"64.128.112.215",
        "phone-number": "+5511991234556",
        "document":{
           "type":"CPF",
           "number":"31192071280"
        }
     },
      "cart": [
          {
              "quantity": 1,
              "description": "Action figure - Spider-man",
              "category": "Collectibles",
              "type": "digital",
              "unit-price": 50.00
          }
      ]
  }'

{
      "transaction": {
        "code": "111181153",
        "reference": "REF-RAW-CC-1539193167",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "[email protected]",
        "date-created": "2018-10-10T14:39:32.991217999-03:00"
      }
    }

📘

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.

Updated 20 days ago