Raw Card Payment

The raw card payment method allows merchants to process transactions by directly submitting card details.
This method requires strict security controls to protect sensitive payment information.

❗️ PCI Compliance Required

This payment method is only available for merchants who are PCI DSS compliant.
Handling raw card data requires adherence to strict security standards to protect customer information.

Supported integration models

Raw card payment supports two integration models:

Rigid model
Flexible model

Both models use the same transaction creation endpoint, but differ in how the charge object is sent and how the card method is validated.

Debit card is available only in the raw card integration flow. Tokenized card currently supports credit card only.

Raw Card Transaction Flow

Customer → Merchant: The customer completes a purchase on the merchant website.
Merchant → API: The merchant server validates the request data and sends the transaction.
API → Merchant: The API processes the request and returns the transaction result.
Merchant → Customer: The merchant communicates the transaction outcome to the customer.

Step 1: Collect the required data

Before submitting the transaction, collect all required information related to:

integration
order
payer
charge

The charge object must follow one of the supported card models described below.

You can also check the reference pages for supported limits, currencies, and languages.

Step 2: Submit the payment request

Send a POST request to the transaction creation endpoint with the integration, order, charge, and payer objects.

Rigid model

In the rigid model, the merchant explicitly informs the expected card method.

Supported request combinations

`charge.type`	Required object
`CREDIT_CARD`	`credit_card`
`DEBIT_CARD`	`debit_card`

Example: credit card request

{
  "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": "John Doe"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "192.0.2.146",
    "person": {
      "name": "John Doe",
      "birth_date": "1970-01-01",
      "document": {
        "type": "CPF",
        "number": "98765432101"
      },
      "phone": {
        "country_code": "55",
        "number": "44900000000"
      }
    }
  }
}

Example: debit card request

{
  "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": "DEBIT_CARD",
    "debit_card": {
      "raw": {
        "number": "4073020000000002",
        "cvc": "123",
        "expiration_month": "12",
        "expiration_year": "2028"
      },
      "holder_name": "John Doe"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "192.0.2.146",
    "person": {
      "name": "John Doe",
      "birth_date": "1970-01-01",
      "document": {
        "type": "CPF",
        "number": "98765432101"
      },
      "phone": {
        "country_code": "55",
        "number": "44900000000"
      }
    }
  }
}

Rigid model response

In the response, the API returns the card brand and the actual method identified during issuer processing.

{
  "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",
  "charge": {
    "type": "CREDIT_CARD",
    "credit_card": {
      "brand": "MASTERCARD",
      "type": "CREDIT",
      "first_digits": "411111",
      "last_digits": "1111"
    }
  }
}

Rigid model validation error

If the card type informed in the request does not match the type reported by the issuing bank, the API returns an error.

{
  "errors": [
    {
      "message": "The card type provided does not match the type reported by the issuing bank.",
      "location": "body.charge.type"
    }
  ]
}

Flexible model

In the flexible model, the merchant sends a generic card object and the actual method is defined by the issuer.

Supported request combination

`charge.type`	Required object
`CARD`	`card`

Example: flexible card request

{
  "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": "CARD",
    "card": {
      "raw": {
        "number": "4073020000000002",
        "cvc": "123",
        "expiration_month": "12",
        "expiration_year": "2028"
      },
      "holder_name": "John Doe"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "192.0.2.146",
    "person": {
      "name": "John Doe",
      "birth_date": "1970-01-01",
      "document": {
        "type": "CPF",
        "number": "98765432101"
      },
      "phone": {
        "country_code": "55",
        "number": "44900000000"
      }
    }
  }
}

Flexible model response

The response returns the actual card method used during issuer processing.

{
  "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",
  "charge": {
    "type": "CARD",
    "card": {
      "brand": "MASTERCARD",
      "type": "DEBIT",
      "first_digits": "411111",
      "last_digits": "1111"
    }
  }
}

Step 3: Process the API response

On success, the API returns the transaction details, including:

transaction identifiers
current status
amount and currency
card brand
masked card information
card method identified during processing

Use charge.card.type, charge.credit_card.type, or charge.debit_card.type according to the selected model to determine the effective card method returned by the issuer flow.

Step 4: Handle transaction status

The status field indicates the current transaction state at the moment the request is processed.

You can track updates by:

using the configured notification_url
querying the transaction status afterward

Important behavior differences between models

Behavior	Rigid model	Flexible model
Merchant informs expected method	Yes	No
Issuer-defined method returned in response	Yes	Yes
Type mismatch validation	Yes	No
Recommended for separate credit/debit checkout flows	Yes	No
Recommended for generic card entry flows	No	Yes

Error handling

If the request fails, the API returns an HTTP status code different from success and an errors array describing the problem.

Example:

{
  "errors": [
    {
      "message": "The card type provided does not match the type reported by the issuing bank.",
      "location": "body.charge.type"
    }
  ]
}

For the complete list of possible errors and reason codes, refer to the API reference.