---
title: "Create a Transaction"
method: POST
path: "/v3/transactions"
tags: ["Direct API"]
---

# Create a Transaction

`POST /v3/transactions`

Creates a new transaction. You can use this endpoint to create payments when using:
- Raw credit card (only available for PCI merchants)
- Credit card token
- Card on File token (Token stored by PagSeguro)
- Google Pay
- Pix
- PSE Avanza
- Nequi

For the accepted document types and validation rules per country, see [Document Validation](https://developers.international.pagseguro.com/boacompra/reference/document-validation).

## Request body

- TransactionRequest — Request body for creating a transaction.
  - `integration` Integration, required — Object containing the integration data referring to the Merchant Store.
    - `reference` string, required — Transaction reference code in the merchant's store.
    - `notification_url` string, url, required — PagSeguro uses the URL to send notifications after the transaction status changes.
    - `language` 'en_US' | 'es_ES' | 'pt_BR' | 'pt_PT' | 'tr_TR', required — Language used when communicating with buyers. - `en_US`: English - United States - `es_ES`: Spanish - Spain - `pt_BR`: Portuguese - Brazil - `pt_PT`: Portuguese - Portugal - `tr_TR`: Turkish - Turkey
    - `redirect_urls` RedirectUrls — URLs to redirect the buyer after the transaction is finished.
      - `success` string, url, required — URL used to redirect users after successfully completing the checkout process.
      - `failure` string, url, required — URL used to redirect users after failing to complete the checkout process.
  - `order` Order, required — Contains the list of products purchased by the customer from the merchant's store along with their respective values.
    - `currency` 'BRL' | 'CLP' | 'COP' | 'MXN' | 'PEN' | 'USD', required — Currency for charging the transaction (ISO 4217). List of currencies available for PagSeguro: | ISO Code | Currency | |----------|-------------------------| | BRL | Brazilian Real (Brazil) | | CLP | Chilean Peso (Chile) | | COP | Colombian Peso (Colombia) | | MXN | Mexican Peso (Mexico) | | PEN | Nuevo Sol (Peru) | | USD | Dollar (USA) |
    - `items` object[], required — List of items purchased by the customer.
      - `quantity` integer, required — Number of items selected by the customer.
      - `description` string, required — Item description. Accepted characters: Uppercase (A-Z), lowercase (a-z), and numbers (0-9).
      - `unit_price` number, float, required — Price per unit. The PagSeguro API supports amounts starting from 0.01. However, the minimum and maximum transaction limits vary by country and payment method. We recommend using the values listed below: | Country | Payment Method | Minimum Total Amount | Maximum Total Amount | ISO Code Currency | Accepted Brands | |----------|------------------------|----------------------|----------------------|-------------------|------------------------------------------------------------| | Brazil | All credit card brands | 1.00 | 40000.00 | BRL | American Express, Diners, MasterCard, Visa, Elo, Hipercard | | Chile | All credit card brands | 0.01 | 1000000.00 | CLP | American Express, Diners, MasterCard, Visa | | Colombia | All credit card brands | 0.01 | 38000000.00 | COP | American Express, Diners, MasterCard, Visa | | Mexico | All credit card brands | 0.01 | 74000.00 | MXN | American Express, Diners, MasterCard, Visa | | Peru | All credit card brands | 0.01 | 34000.00 | PEN | American Express, Diners, MasterCard, Visa |
  - `charge` Charge, required — Object containing the payment details required to generate the transaction.
    - `country` string, required — The country where the transaction originates, represented by a two-letter ISO 3166-1 alpha-2 code.
    - `method` 'NIUBIZ_WALLET' | 'PIX' — Required for payments using e-Wallet. It defines the payment method used for the transaction.
    - `installments` integer — If the payment is processed in installments, specify the total number of monthly installments selected by the customer.
    - `type` 'CREDIT_CARD' | 'DEBIT_CARD' | 'EFT' | 'OBT' | 'POSTPAY' | 'PREPAY' — Specifies the type of payment method used for the transaction. - Required for transactions that **do not** use an e-Wallet. - Not applicable for e-Wallet payments, since in that case the payment method is determined by the `method` parameter.
    - `initiated_by` 'CUSTOMER' | 'MERCHANT' — Indicates who initiated the transaction. If the transaction was initiated by the customer interaction, use `CUSTOMER` (CIT - Customer Initiated Transaction). If the transaction was initiated by the merchant without direct customer interaction, use `MERCHANT` (Merchant Initiated Transaction).
    - `credit_card` union — Credit card details. This object is required for transactions that do not use an e-Wallet.
      - ChargeCreditCardRaw — Credit card details when using raw card information. This object is required when using the raw credit card option.
        - `raw` object, required
          - `number` string, required — The card number.
          - `cvc` string, required — The card security code (CSV).
          - `expiration_month` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '12', required — This parameter is required. Credit card expiration month.
          - `expiration_year` string, required — Credit card expiration year.
        - `holder_name` string, required — The cardholder's name on the credit card. Must be between 2 and 26 characters. Only letters (A-Z, a-z) and special characters (,.'-) are allowed. Spaces are not allowed at the beginning or end. Words must be separated by exactly one space.
        - `store` boolean — Indicates whether to store the credit card information for future transactions. Use this option if you want to save the card details for subsequent purchases. This option is related to the Card on File feature. The default value is `false`.
      - ChargeCreditCardToken — Credit card details when using a token credit card generated in the frontend. The `store` parameter is required when using the token credit card option.
        - `token` string, required — Credit card token generated by PagSeguro's JS.
        - `holder_name` string, required — The cardholder's name on the credit card. Must be between 2 and 26 characters. Only letters (A-Z, a-z) and special characters (,.'-) are allowed. Spaces are not allowed at the beginning or end. Words must be separated by exactly one space.
        - `store` boolean — Indicates whether to store the credit card information for future transactions. Use this option if you want to save the card details for subsequent purchases. This option is related to the Card on File feature. The default value is `false`.
      - ChargeCardOnFileToken — Credit card details when using a Card on File token (Token stored by PagSeguro). This object is required when using the Card on File token option.
        - `id` string, required — Card on File token generated by PagSeguro.
        - `cvv` string — The card security code.
      - ChargeCreditCardGooglePay — Credit card details when using Google Pay. This object is required when using the Google Pay option.
        - `google_pay` object, required
          - `token` string, required — The token returned by Google Pay.
        - `holder_name` string, required — The cardholder's name on the credit card. Must be between 2 and 26 characters. Only letters (A-Z, a-z) and special characters (,.'-) are allowed. Spaces are not allowed at the beginning or end. Words must be separated by exactly one space.
    - `authentication_method` AuthenticationMethod — Contains 3D Secure authentication details for the credit card transaction.
      - `type` string, required — Type of authentication method used. Currently only `3DS` is supported.
      - `cavv` string, required — Cardholder Authentication Verification Value (CAVV).
      - `xid` string — Transaction Identifier used in 3D Secure (optional in 3DS 2.x).
      - `eci` string, required — Electronic Commerce Indicator. Indicates the result of the authentication.
      - `version` string, required — 3D Secure protocol version used for the authentication.
      - `dstrans_id` string, required — Directory Server Transaction ID (DSTransID), used in 3D Secure 2.x.
  - `payer` Payer, required — Contains information about the Customer who made the purchase on the Merchant.
    - `email` string, email, required — Payer E-mail used to execute the order.
    - `ip` string, required — Payer IP used to execute the order. Accepts IPv4 or IPv6.
    - `person` PayerPerson, required — Payer's personal information.
      - `name` string, required — The payer's full name. Must be between 4 and 50 characters long and contain at least two words. The first word must have at least 2 characters, while middle and last names can have between 1 and 40 characters. Words must be separated by exactly one space. Accepted characters: uppercase and lowercase letters (A-Z, a-z), special characters (àáâäãåąčćęèéêëėįìíîïłńòóôöõøùúûüųūÿýżźñçčšžÀÁÂÄÃÅĄĆČĖĘÈÉÊËÌÍÎÏĮŁŃÒÓÔÖÕØÙÚÛÜŲŪŸÝŻŹÑßÇŒÆČŠŽ∂ð/,.'&-). Leading and trailing spaces are not allowed.
      - `birth_date` string, date — Payer's birth date in YYYY-MM-DD format.
      - `document` object, required — Contains the payer's identification document details for the transaction. TODO - add link to the Document validation page.
        - `type` string, required — Document type.
        - `number` string, required — Document number.
      - `phone` object, required — Contains the payer's phone information.
        - `country_code` string, required — Phone country code.
        - `number` string, required — Phone number.

## Response `201`

Successful transaction creation.

- TransactionResponse — Response for a successful transaction creation.
  - `code` string, uuid — Transaction UUID code.
  - `reference` string — Transaction reference code in the merchant's store.
  - `status` string — Status of the created transaction.
  - `amount` number, float — The amount charged for the transaction.
  - `installments` number — The number of installments of the transaction.
  - `currency` string — The currency used for billing.
  - `country` string — The country of origin informed in the transaction.
  - `created_at` string, date-time — Transaction creation date in Coordinated Universal Time (UTC).
  - `payment_instructions` PaymentInstructions — Contains payment instructions for the buyer, such as a redirect URL or QR code for completing the payment.
    - `interaction_type` string[] — Indicates the type of interaction required from the buyer to complete the payment.
    - `redirect` Redirect
      - `url` string, url — The URL to which the buyer should be redirected to complete the payment.
    - `type` 'QR_CODE' — The type of code presented to the buyer.
    - `value` string — The raw code value to be used or displayed to the buyer.
    - `image` string, url — URL of the QR code image.

## Other responses

- `400` — Bad Request - The request was malformed or contained invalid data.
- `401` — Unauthorized - Authentication failed due to missing or invalid credentials.
- `422` — Unprocessable Entity - The request was well-formed but could not be processed due to semantic errors.

---

[API](https://skmtc.net/pagseguro/apis/pagseguro-international-api.md) · [All operations](https://skmtc.net/pagseguro/apis/pagseguro-international-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pagseguro/pagseguro-international-api/revisions/032af0550731/schema)