Create a Single-Step Card Payment

This guide shows you how to process a complete single-step payment transaction with the Getnet Global API. In this flow, you capture the payment directly, without a previous authorization.

Requirements

Before following the steps, you need to:

  • Create your account by contacting the Integration Support team to get your API credentials client_id and client_secret.
  • Generate your token with your credentials using the Authentication endpoint.
information icon

Getnet provides a Postman Collection to help you replicate these use cases locally. You can also test the API in sandbox with the API Reference in the documentation.

Use case specifics

When integrating any Getnet solution, market-specific requirements apply. Be sure to review the resources below before you go live:

You can also use test cards to simulate specific scenarios. You can find the specific requirements for each country in the Developer Resources section of the Getnet documentation.

information icon
Payment facilitators: When Getnet enables your credential as a payment facilitator, you must also send the data.sub_merchant object on this request. See Payment Facilitators.

Single-step payment process

This section guides you through the process of creating a single-step payment transaction with the Getnet Global API. You'll learn how to capture payment directly in one step and optionally verify the transaction status.

The following diagram provides an overview of the single-step payment process:

Tokenize card data (optional)

You can use tokenization instead of sending the raw card number in your payment request. Tokenization enhances security and reduces PCI DSS compliance scope. To use a tokenized card:

  1. Tokenize the card by calling the Card Tokenization endpoint with the card_number and customer_id.
  2. In your payment request, replace the card.number field with card.number_token using the token value received from the tokenization endpoint.
When using number_token, you must exclude the card.number property from the request. For complete details on tokenization, see the Tokenization and Vault documentation.

Step 1: Capture the payment

In a single-step payment, you capture the payment with the Create - Authorize endpoint. This step validates the customer's payment details and directly transfers the funds.

information icon
Country-specific requirements: Some markets may require additional mandatory fields. In Uruguay, you must include a rates array with the iva key and set data.payment.transaction_type to FULL. Send regional_regulation_code only when the transaction qualifies for a regional regulation or tax benefit. Each entry takes a code (17934 or 19210) and an optional invoice of up to 9 alphanumeric characters. When you omit the invoice, Getnet derives it from your order_id. Review the Taxes and Regulations reference for more information.
For the single-step process, you must set the data.payment.payment_method attribute in your request to CREDIT or DEBIT. This setting captures the funds immediately. The table below lists the minimum fields you need to send:
AttributeDescriptionRequired
idempotency_keyUnique identifier to prevent duplicate charges.Yes
order_idMerchant reference ID used for reconciliation.Yes
request_idTrace identifier for idempotency audits and support follow-up.Recommended
data.amountTransaction amount in cents.Yes
data.currencyISO currency code used in the transaction.Yes
data.customerCustomer details (name, email, phone, document, full billing address). Mandatory in production to avoid antifraud blocks.Yes (Prod)
data.payment.payment_methodMust be CREDIT or DEBIT for a single-step flow.Yes
data.payment.transaction_typeDefines how the transaction is processed (FULL, INSTALL_NO_INTEREST, INSTALL_WITH_INTEREST).Yes
data.payment.number_installmentsNumber of installments (use 1 for a single payment).Yes
data.payment.cardCard data set (number, brand, expiration_month, expiration_year, security_code, cardholder_name).Yes
data.additional_data.deviceDevice fingerprint information (ip_address, device_id, finger_print) for antifraud analysis.Yes (Prod)

The objects required for antifraud validation must include the following fields:

Object / FieldDescription
customer.first_nameCustomer's first name
customer.last_nameCustomer's last name
customer.emailCustomer email address
customer.phone_numberPhone number (international format)
customer.document_typeDocument type (e.g., CPF, DNI, etc.)
customer.document_numberDocument number (without punctuation)
customer.billing_address.streetStreet name
customer.billing_address.numberAddress number
customer.billing_address.districtDistrict or neighborhood
customer.billing_address.cityCity
customer.billing_address.stateState or province
customer.billing_address.countryCountry code (ISO)
customer.billing_address.postal_codePostal or ZIP code
additional_data.device.ip_addressCustomer’s IP address
additional_data.device.device_idDevice fingerprint session ID (UUIDv4)
additional_data.device.finger_printFingerprint hash generated by the antifraud script
information icon
Antifraud data is mandatory for production environments. Antifraud teams automatically block transactions that lack device fingerprint or customer information, to prevent fraud. See the Antifraud documentation for complete implementation details.
At the end of a successful authorization, you receive a payment_id that identifies this transaction.

The following code block shows a single-step payment request:

Bash
curl --request POST \ --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \ --header 'x-transaction-channel-entry: XX' \ --data'{ "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9", "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3", "order_id": "ORDER-10187383", "data": { "amount": 118708, "currency": "BRL", "customer_id": "test", "customer": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "document_type": "CPF", "document_number": "12345678900", "phone_number": "+5511999999999", "billing_address": { "street": "Av. Paulista", "number": "1000", "complement": "Apto 101", "district": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BR", "postal_code": "01310-100" } }, "payment": { "payment_method": "CREDIT", "save_card_data": false, "transaction_type": "FULL", "number_installments": 1, "soft_descriptor": "LOJA*TESTE*COMPRA-123", "dynamic_mcc": 1799, "card": { "number": "5155901222260000", "expiration_month": "09", "expiration_year": "30", "cardholder_name": "Card Holder", "security_code": "517" } }, "additional_data": { "device": { "ip_address": "192.168.1.1", "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9", "finger_print": "1a2b3c4d5e6f7g8h9i0j" } } } }'
The following example shows a response with status as APPROVED:
JSON
{ "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9", "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09", "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75", "order_id": "ORDER-10187383", "amount": 118708, "currency": "BRL", "status": "APPROVED", "payment_method": "CREDIT", "received_at": "2025-10-31T13:40:47.382Z", "transaction_id": "MCC50205G1020", "original_transaction_id": "MCC50205G1020", "authorized_at": "2025-10-31T13:40:47.382Z", "reason_code": "00", "reason_message": "captured", "acquirer": "GETNET", "soft_descriptor": "LOJA*TESTE*COMPRA-123", "brand": "MASTERCARD", "authorization_code": "204050", "acquirer_transaction_id": "405030304060404030501060" }

Step 2: Check the payment status (optional)

The Create - Authorize response shows the status as APPROVED.

Some payments process asynchronously, so the status can change over time. To get the latest status of a transaction, use the Get Transaction endpoint.

For real-time updates without polling, use Webhooks to receive notifications for every status change.

Next steps

Now that you have successfully created a single-step payment, you can explore more features of the Getnet Global API:

On this page

Create a Single-Step Card Payment