Ir para o conteúdo

API de Pagamentos

🤖 Explicar com IA

A API de Pagamentos é uma ferramenta de processamento de pagamentos que permite às empresas aceitarem e processarem pagamentos online de forma segura e eficiente. Com esta API, as empresas podem integrar funcionalidades de processamento de pagamentos em seus sites, aplicações e outras soluções de software.

Ela oferece suporte aos principais métodos de pagamento, incluindo cartões de crédito, cartões de débito e carteiras digitais. Também fornece recursos como processamento de pagamentos em tempo real, conversão automática de moeda e prevenção de fraudes.

Todas as cobranças solicitam 3DS ao banco do titular do cartão por padrão.

Criar uma solicitação de pagamento

Endpoint

POST /v1/payments/

Este endpoint constrói uma página de faturamento segura única, baseada nos seguintes parâmetros. Observe que você deve direcionar o titular do cartão para a página gerada, onde ele inserirá os dados do método de pagamento. Enviaremos a resposta da transação para a return_url.

Campos:

Parâmetro Descrição Tipo Obrigatório
amount Valor total a cobrar (formato decimal, ex: 99.99) string true
description Uma descrição do pagamento ou serviço string true
currency Um código de moeda ISO-4217 válido, por exemplo USD, CAD, CRC, EUR. string true
items Nome(s) do(s) produto(s) ou serviço(s). É apenas um rótulo informativo. array true
return_url Redirecionaremos para esta URL após a conclusão do pagamento com o id_payment concatenado como um parâmetro de consulta, para que você possa consultar o status da transação. string true

Exemplo de Solicitação:

curl -X POST 'https://api.4geeks.io/v1/payments/' \
-u "sk_test_51O62xYzAbcDef123:" \
-H 'Content-Type: application/json' \
-d '{
    "amount": "500.00",
    "description": "Premium subscription payment",
    "currency": "USD",
    "items": ["Premium Plan - Monthly"],
    "return_url": "https://example.com/payment-result"
}'

import requests
from requests.auth import HTTPBasicAuth

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/v1/payments/',
    auth=HTTPBasicAuth(api_key, ""),
    json={
        "amount": "500.00",
        "description": "Premium subscription payment",
        "currency": "USD",
        "items": ["Premium Plan - Monthly"],
        "return_url": "https://example.com/payment-result"
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = Buffer.from(`${apiKey}:`).toString("base64");

fetch("https://api.4geeks.io/v1/payments/", {
    method: "POST",
    headers: {
        Authorization: `Basic ${credentials}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: "500.00",
        description: "Premium subscription payment",
        currency: "USD",
        items: ["Premium Plan - Monthly"],
        return_url: "https://example.com/payment-result",
    }),
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = btoa(`${apiKey}:`);

const headers = new HttpHeaders({
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
});

const payload = {
    amount: "500.00",
    description: "Premium subscription payment",
    currency: "USD",
    items: ["Premium Plan - Monthly"],
    return_url: "https://example.com/payment-result",
};

this.http
    .post("https://api.4geeks.io/v1/payments/", payload, { headers })
    .subscribe((data) => console.log(data));

Resposta (202 Accepted):

{
    "code": 202,
    "title": "Action required",
    "content": "Show the checkout page to complete payment.",
    "data": {
        "id_payment": "pay_1ABC123XYZ456",
        "redirect": "https://console.4geeks.io/checkout/?data=eyJyZXR1cm5fdXJsIjogImh0dHA6Ly9leGFtcGxlLmNvbS9wYXltZW50LXJlc3VsdCIsICJ0ZXN0IjogdHJ1ZSwgImhhc19jdXN0b21lciI6IGZhbHNlLCAiY29tcGFueV9lbWFpbCI6ICJzdXBwb3J0QDRnZWVrcy5pbyIsICJwcm9kdWN0IjogeyJ0b3RhbF9wcmljZSI6IDUwMC4wMCwgInByaWNlIjogNTAwLjAwLCAiY3VycmVuY3kiOiAiVVNEIiwgIm5hbWUiOiAiUHJlbWl1bSBzcWJzY3JpcHRpb24gcGF5bWVudCIsICJkZXNjcmlwdGlvbiI6IFsiUHJlbWl1bSBQbGFuIC0gTW9udGhseSJdfSwgInN0YXRlbWVudF9kZXNjcmlwdG9yIjogWyI0R0VFS1MiXSwgImNvbXBhbnlfbmFtZSI6ICI0R2Vla3MgUGF5bWVudHMifQ=="
    }
}

Obter um pagamento

Endpoint

GET /v1/payments/{id}

Recupera os detalhes de uma transação de pagamento específica pelo seu ID. Este endpoint retorna as informações completas da transação, incluindo status, valor, moeda, detalhes do cliente e informações do método de pagamento.

Parâmetros de Caminho (Path Parameters):

Parâmetro Descrição Tipo Obrigatório
id O ID único do pagamento (ex: pay_1ABC123XYZ456) string true

Parâmetros de Consulta (Query Parameters):

Parâmetro Descrição Tipo Obrigatório
test Filtrar pelo modo de teste (true/false) boolean false

Exemplo de Solicitação:

curl -X GET 'https://api.4geeks.io/v1/payments/pay_1ABC123XYZ456' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Resposta (200 OK):

{
    "id": "pay_1ABC123XYZ456",
    "amount": "500.00",
    "currency": "USD",
    "description": "Premium subscription payment",
    "status": "completed",
    "items": ["Premium Plan - Monthly"],
    "customer_email": "customer@example.com",
    "return_url": "https://example.com/payment-result",
    "payment_method": "card",
    "card_last4": "4242",
    "card_brand": "visa",
    "created_at": "2025-12-04T10:30:00Z",
    "updated_at": "2025-12-04T10:35:00Z",
    "test": true
}

Resposta de Erro (404 Not Found):

{
    "code": 404,
    "title": "Payments not found",
    "content": "Errors were encountered during the search, please verify the data.",
    "type": "danger"
}

Obter todos os pagamentos

Endpoint

GET /v1/payments/internal

Recupera uma lista paginada de todos os pagamentos. Suporta opções de filtragem e ordenação.

Parâmetros de Consulta (Query Parameters):

Parâmetro Descrição Tipo Obrigatório
status Filtrar pelo status do pagamento (succeeded, etc.) string false
test Filtrar pelo modo de teste (true/false) boolean false

Exemplo de Solicitação:

curl -X GET 'https://api.4geeks.io/v1/payments/?status=succeeded&test=false' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Resposta (200 OK):

[
    {
        "id": "7f277445-d4d0-47e2-bd6f-4664e4480778",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "5c35a9f5-cd2a-4bf5-a0e2-d946eedeefeb",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-11-04T14:33:25.690012Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    },
    {
        "id": "e7d9a0ea-58fb-45a0-8005-e2c314bcf3d1",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "9928c043-e480-4b77-aa31-88de9ae52e7c",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-09-17T20:58:39.797400Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    }
]

Tratamento de Erros

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Abaixo estão erros comuns específicos para a API de Pagamentos:

Código de Status Tipo de Erro Descrição
400 Bad Request Campos obrigatórios ausentes ou formato de valor/moeda inválido.
401 Unauthorized Autenticação de Chave de API ausente ou inválida.
402 Payment Required Método de pagamento recusado ou saldo insuficiente.
404 Not Found O ID do pagamento não existe.
409 Conflict Solicitação de pagamento duplicada (verificação de idempotência).
500 Server Error Erro inesperado do servidor durante o processamento do pagamento.

Exemplo: Não Autorizado (401)

{
    "detail": "Invalid API key format."
}

Exemplo: Pagamento Falhou (402)

{
    "error": {
        "code": 402,
        "type": "payment_failed",
        "message": "Card declined. Please try another payment method.",
        "decline_reason": "insufficient_funds"
    }
}

Problemas Comuns e Solução de Problemas

Problema: 401 Unauthorized

  • Verifique se sua Chave de API está correta e se não foi rotacionada recentemente.
  • Certifique-se de que o cabeçalho Basic Auth inclui os dois pontos finais (:).
  • Verifique se o tipo de chave (test/live) corresponde ao seu ambiente.