Create Credit Card Payment

Creates a credit card payment with configurable installments.

POST /payments/v1/card

cURL

curl -X POST "https://api.gates2b.com/payments/v1/card" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientMode": "noNeedToSpecify",
    "amount": 3.05,
    "expire_at": "2025-12-30T03:00:00.000Z",
    "installments": 12
  }'

Success

{
  "id": 3577,
  "amount": 3.05,
  "description": null,
  "clientMode": "noNeedToSpecify",
  "redirect_url": null,
  "email": null,
  "phoneNumber": null,
  "document_type": null,
  "expire_at": "2025-12-30T03:00:00.000Z",
  "document_client": null,
  "document_type_client": null,
  "name_client": null,
  "id_transaction": "7ddc71cb-66a8-4c48-b509-706b2db0e37a",
  "emv": null,
  "name_receiver": "Clever Meireles Lopes Junior",
  "international_status": "WAITING_PAYMENT",
  "status": "Aguardando pagamento",
  "checkout_id": 1,
  "checkout_url": "https://pay.gates2b.com/7ddc71cb-66a8-4c48-b509-706b2db0e37a",
  "createdAt": "2025-12-10T19:53:09.078Z",
  "updatedAt": "2025-12-10T19:53:09.078Z",
  "installments": 12
}

Authorization · string · required

The Bearer authentication token is required to access this endpoint.

clientMode · string · required

Defines how customer data is handled. - noNeedToSpecify: No customer data required. - fillDataNow: Customer data must be provided now. - requestCheckout: Customer data will be collected via checkout.

amount · number · required

Payment amount.

expire_at · string · required

Expiration date and time in ISO 8601 format.

installments · number · required

Number of installments (1 to 24).

Response

id · number

Unique ID of the created transaction.

amount · number

Payment amount.

description · string

Payment description.

clientMode · string

Customer data handling mode.

redirect_url · string

Redirect URL after payment.

email · string

Customer email.

phoneNumber · string

Customer phone number.

document_type · string

Customer document type.

expire_at · string

Transaction expiration date and time.

document_client · string

Customer document.

document_type_client · string

Customer document type.

name_client · string

Customer name.

id_transaction · string

Transaction ID (UUID).

emv · string

Card EMV data (when applicable).

name_receiver · string

Receiver name.

international_status · string

International transaction status. Possible values: - WAITING_PAYMENT: Waiting for payment - PAID: Paid - DENIED: Denied - CANCELED: Canceled - REFUNDED: Refunded

status · string

Transaction status in Portuguese.

checkout_id · number

Generated checkout ID.

checkout_url · string

Checkout URL where the customer can fill in card details.

createdAt · string

Transaction creation date and time (ISO 8601).

updatedAt · string

Last update date and time (ISO 8601).

installments · number

Configured number of installments.

cURL

curl -X POST "https://api.gates2b.com/payments/v1/card" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientMode": "noNeedToSpecify",
    "amount": 3.05,
    "expire_at": "2025-12-30T03:00:00.000Z",
    "installments": 12
  }'

Success

{
  "id": 3577,
  "amount": 3.05,
  "description": null,
  "clientMode": "noNeedToSpecify",
  "redirect_url": null,
  "email": null,
  "phoneNumber": null,
  "document_type": null,
  "expire_at": "2025-12-30T03:00:00.000Z",
  "document_client": null,
  "document_type_client": null,
  "name_client": null,
  "id_transaction": "7ddc71cb-66a8-4c48-b509-706b2db0e37a",
  "emv": null,
  "name_receiver": "Clever Meireles Lopes Junior",
  "international_status": "WAITING_PAYMENT",
  "status": "Aguardando pagamento",
  "checkout_id": 1,
  "checkout_url": "https://pay.gates2b.com/7ddc71cb-66a8-4c48-b509-706b2db0e37a",
  "createdAt": "2025-12-10T19:53:09.078Z",
  "updatedAt": "2025-12-10T19:53:09.078Z",
  "installments": 12
}

Important Notes

Transaction Status

After creation, the transaction is in status WAITING_PAYMENT (Waiting for payment). Possible statuses are:

• WAITING_PAYMENT: Waiting for payment
• PAID: Payment approved and processed
• DENIED: Payment declined
• CANCELED: Transaction canceled
• REFUNDED: Payment refunded

Checkout URL

The returned checkout_url can be used to direct the customer to a hosted checkout page, where they can securely enter card details.

Installments

• Available installments: 1 to 24 installments
• Minimum amount: Check your account-specific configuration
• Fees: Automatically calculated based on configuration and number of installments

Client Mode

The clientMode field defines how customer data will be handled:

• noNeedToSpecify: No customer data required at creation
• fillDataNow: Customer data must be provided in the payload
• requestCheckout: Customer data will be collected via checkout

Expiration

The expiration date (expire_at) must be provided in ISO 8601 format. After expiration, the transaction can no longer be paid.

HTTP Status Codes

• 201: Payment created successfully
• 400: Invalid payload data
• 401: Missing or invalid authentication token
• 500: Internal error creating payment

Validations

1. Amount: Must be greater than 0
2. Installments: Must be between 1 and 24
3. Expiration Date: Must be a future date

Best Practices

1. Store the Transaction ID: Save the id_transaction in your database along with the order 2. Checkout URL: Use checkout_url to redirect the customer to the secure checkout 3. Webhook: Configure webhooks to receive status change notifications 4. Expiration: Set a proper expiration time (e.g., 30 minutes, 24 hours) 5. Installments: Consider fee impact when choosing the number of installments