🔗
A criação de vendas com cartão com captura manual, é realizada na rota POST /v1/charges/

🔗
A captura é realizada na rota POST /v1/transactions/

Captura Manual - como e quando utilizar

A captura manual permite que o estabelecimento tenha controle sobre quando e a quantia do valor da autorização a ser confirmada.

Esse modelo possui um nicho mais específico onde há uma gestão de negócio enquanto uma transação está autorizada, para que aja uma confirmação posterior quanto a garantia de serviço e valor.

Os ramos de estabelecimento que mais utilizam esse modelo são: Hotéis e Pousadas, Locadoras, Concessionárias, Lojas de eletrodomésticos e Produtos sob encomenda.

Por padrão, Hotéis, Pousadas e Locadoras utilizam a reserva do limite do cartão como caução para garantir um pagamento prévio da estadia. Quando o hospede se retira, a caução é confirmada de forma parcial ou integral de acordo as políticas do estabelecimento.

As Concessionária costumam efetuar uma autorização como sinal de interesse de compra de um veículo, garantindo o pagamento parcial do veículo previamente.

Já as Lojas de eletrométricos, ou Produtos sob encomenda, costumam trabalhar com estoques, onde há a possibilidade de o produto solicitado não estar disponível após a compra. Para evitar atritos, o estabelecimento faz apenas reserva do limite, para então confirmar o estoque e consequentemente a captura da transação. Dessa forma, caso o produto não esteja disponível, será possível cancelar a autorização e retornar o limite imediatamente ao comprador.

Casos de Uso

Abaixo alguns exemplos de caso de uso.

Hosteís e Pousadas (Caução)

No check-in é realizada uma autorização.
O limite fica reservado no cartão.
O hóspede utiliza serviços do hotel.
No check-out é definido o valor final.
O hotel captura apenas o valor devido.
O restante da reserva é liberado.

flowchart TB
    A["🏨 Check-in"] --> B["💳 Pré-autorização<br>Limite reservado"]
    B -- Transação aguardando captura --> C["🛎️ Consumos durante hospedagem"]
    C --> D["🏁 Check-out"]
    D --> E["🧾 Estabelecimento calcula o valor final"]
    E --> F["💰 Capturar valor consumido"] & G["🔓 Liberar saldo remanescente"]
    F --> H["✅ Processo concluído"]
    G --> H

     F:::success
     G:::cancel
     H:::success
    classDef success fill:#e8f5e9,stroke:#2e7d32
    classDef cancel fill:#ffebee,stroke:#c62828
    style F color:#000000
    style G color:#000000
    style H color:#000000

Locadoras (Caução)

Na retirada do veículo é realizada autorização.
O limite fica reservado no cartão.
O cliente utiliza o veículo durante o período da locação.
Na devolução é calculado o valor final da locação, incluindo eventuais adicionais.
A locadora captura apenas o valor devido.
O restante da reserva é liberado ao cliente.

flowchart TB

    A["🚗 Retirada"] --> B["💳 Pré-autorização"]
    B --> C["🔒 Caução reservado"]
    C --> D["🛣️ Utilização do veículo"]
    D --> E["⛽ Combustível<br/>🛣️ Pedágios<br/>⏰ Diárias extras"]
    E --> F["🔑 Devolução"]
    F --> G["🧾 Valor final da locação"]
    G --> H["💰 Captura"]
    H --> I["✅ Pagamento concluído"]
    G -.-> J["🔓 Liberação do saldo restante"]
     H:::success
     I:::success
     J:::cancel
    classDef success fill:#e8f5e9,stroke:#2e7d32
    classDef cancel fill:#ffebee,stroke:#c62828
    style H color:#000000
    style I color:#000000
    style J color:#000000

Produtos Sob Encomenda

Cliente realiza a compra.
O limite fica reservado no cartão.
O estabelecimento aguarda a produção/envio do produto.
Quando estiver pronto, realiza a captura.
O valor é efetivamente capturado.

flowchart TB
    A["🛒 Cliente realiza pedido"] --> B["💳 Transação autorizada"]
    B --> C["🔒 Limite reservado<br>(Aguardando captura)"]
    C --> D{"❓ Pedido confirmado?"}
    D -- Sim --> E["🏭 Produção do produto"]
    E --> F["📦 Produto pronto"]
    F --> G["🚚 Produto enviado"]
    G --> H["💰 Capturar transação"]
    H --> I["✅ Pagamento concluído"]
    D -- Não --> J["❌ Cancelar pedido"]
    J --> K["🔓 Limite liberado"]

     H:::success
     I:::success
     J:::cancel
     K:::cancel
    classDef success fill:#e8f5e9,stroke:#2e7d32
    classDef cancel fill:#ffebee,stroke:#c62828
    style H color:#000000
    style I color:#000000
    style J color:#000000

Informações adicionais

🚧
A Captura Manual deve ser solicitada: Por padrão, nossa plataforma considera a captura automática em todas as transações. Caso queira utilizar a captura manual, deverá ser parametrizado na criação da venda.

🚧
Prazo máximo para capturar uma transação: Uma autorização precisa ser capturada dentro prazo estabelecido pela adquirente/autorizadora.
Em uma situação de transação não capturada, ela será automaticamente cancelada e o portador terá o limite retornado ao cartão.
Para que isso não ocorra, é importante que saiba o prazo máximo para efetuar a captura de acordo a adquirente utilizada.
Caso possua dúvidas quanto ao prazo, basta entrar em contato com o nosso suporte para auxiliá-lo.

Exemplos de request e response

Para realizar uma transação com captura manual, basta informar na criação de venda parâmetro payments.capture com o valor "manual".

Caso a transação seja aprovada, ela terá os campos status como PAID e detailed_status como "AUTHORISED_TO_VALIDATE"

Exemplo de requisição e resposta.:

{
    "amount": 2000,
    "order_id": "BR0000-40842775",
    "order_info": "charge description",
    "currency": "BRL",
    "type": "PAYMENT",
    "soft_descriptor": "PAYTEST",
    "client_ip": "174.159.112.123",
    "payments": [
        {
            "payment_method": "card",
            "amount": 2000,
            "installments": 12,
            "create_token": true,
            "capture": "manual",
            "card": {
                "number": "5100010000000106",
                "exp_year": 2025,
                "exp_month": 12,
                "cvv": "1234",
                "holder_name": "Pat Mayer"
            }
        }
    ],
    "customer": {
        "name": "Erma Bergnaum",
        "email": "[email protected]",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "birth_date": "2000-01-01",
        "document_type": "CPF",
        "document_number": "62286843023"
    }
}

{
    "uuid": "4d32aed2-e499-4bf1-8e20-4c2af671e13e",
    "type": "PAYMENT",
    "expiry_date": "2025-03-21T02:59:59Z",
    "status": "PAID",
    "order_id": "BR0000-40842775",
    "order_info": "charge description",
    "currency": "BRL",
    "original_amount": 2000,
    "amount": 2000,
    "paid": 2000,
    "due": 0,
    "refunded": 0,
    "attempts": 1,
    "max_attempts": 5,
    "drop_reason": "",
    "surcharge": false,
    "client_ip": "174.159.112.123",
    "soft_descriptor": "PAYTEST",
    "customer": {
        "uuid": "58d2ea7a-edca-4cc8-9ca9-8c67dd19a1a8",
        "name": "Erma Bergnaum",
        "email": "[email protected]",
        "birth_date": "2000-01-01",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "document_type": "CPF",
        "document_number": "622******23",
        "created_at": "2025-03-18T14:12:36Z",
        "updated_at": "2025-03-18T14:12:36Z"
    },
    "transactions": [
        {
            "uuid": "71b4fd04-961a-450c-ad14-ee45ac564d8c",
            "charge_uuid": "4d32aed2-e499-4bf1-8e20-4c2af671e13e",
            "gateway_id": "aed0195c8509447fafa04a335e65b038",
            "amount": 2000,
            "paid_amount": 2000,
            "status": "PAID",
            "payment_option": "CARD",
            "payment_option_detail": "card",
            "scheme": "MASTERCARD",
            "external_id": "03060348947648721057",
            "transaction_id_reference": null,
            "expected_capture_date": "2025-03-18T14:12:37Z",
            "payment_at": "2025-03-18T14:12:37Z",
            "captured_at": null,
            "auth_num": "001060",
            "auth_response_code": "0",
            "operation_type": "DEBIT",
            "extra": null,
            "payment_number": "510001XXXXXX0106",
            "payer_info": "Erma Bergnaum",
            "expiry_month": 12,
            "expiry_year": 2025,
            "acquirer_network": "REDE",
            "nsu": "000582900825",
            "tid": "",
            "token": "fc439de6b1c04e2cba6ccead817e4695",
            "create_token": true,
            "detailed_status": "AUTHORISED_TO_VALIDATE",
            "currency": "BRL",
            "document_type": "CPF",
            "document_number": "622******23",
            "installments": 12,
            "sub_acquirer": 1001,
            "auth_3ds": null,
            "created_at": "2025-03-18T14:12:38Z",
            "updated_at": "2025-03-18T14:12:38Z"
        }
    ],
    "created_at": "2025-03-18T14:12:36Z",
    "updated_at": "2025-03-18T14:12:36Z"
}

Para realizar a captura, basta solicitar na rota referenciando o UUid da transação em /v1/transactions/{transaction_uuid}/capture

Exemplo de venda com transação capturada:

{
    "uuid": "4d32aed2-e499-4bf1-8e20-4c2af671e13e",
    "type": "PAYMENT",
    "expiry_date": "2025-03-21T02:59:59Z",
    "status": "PAID",
    "order_id": "BR0000-40842775",
    "order_info": "charge description",
    "currency": "BRL",
    "original_amount": 2000,
    "amount": 2000,
    "paid": 2000,
    "due": 0,
    "refunded": 0,
    "attempts": 1,
    "max_attempts": 5,
    "drop_reason": "",
    "surcharge": false,
    "client_ip": "174.159.112.123",
    "soft_descriptor": "PAYTEST",
    "customer": {
        "uuid": "58d2ea7a-edca-4cc8-9ca9-8c67dd19a1a8",
        "name": "Erma Bergnaum",
        "email": "[email protected]",
        "birth_date": "2000-01-01",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "document_type": "CPF",
        "document_number": "622******23",
        "created_at": "2025-03-18T14:12:36Z",
        "updated_at": "2025-03-18T14:12:36Z"
    },
    "transactions": [
        {
            "uuid": "71b4fd04-961a-450c-ad14-ee45ac564d8c",
            "charge_uuid": "4d32aed2-e499-4bf1-8e20-4c2af671e13e",
            "gateway_id": "aed0195c8509447fafa04a335e65b038",
            "amount": 2000,
            "paid_amount": 2000,
            "status": "PAID",
            "payment_option": "CARD",
            "payment_option_detail": "card",
            "scheme": "MASTERCARD",
            "external_id": "03060348947648721057",
            "transaction_id_reference": null,
            "expected_capture_date": "2025-03-18T14:12:37Z",
            "payment_at": "2025-03-18T14:12:37Z",
            "captured_at": "2025-03-18T14:52:43Z",
            "auth_num": "001060",
            "auth_response_code": "0",
            "operation_type": "DEBIT",
            "extra": null,
            "payment_number": "510001XXXXXX0106",
            "payer_info": "Erma Bergnaum",
            "expiry_month": 12,
            "expiry_year": 2025,
            "acquirer_network": "REDE",
            "nsu": "011867974166",
            "tid": "",
            "token": "fc439de6b1c04e2cba6ccead817e4695",
            "create_token": true,
            "detailed_status": "CAPTURED",
            "currency": "BRL",
            "document_type": "CPF",
            "document_number": "622******23",
            "installments": 12,
            "sub_acquirer": 1001,
            "auth_3ds": null,
            "created_at": "2025-03-18T14:12:38Z",
            "updated_at": "2025-03-18T14:12:38Z"
        }
    ],
    "created_at": "2025-03-18T14:12:36Z",
    "updated_at": "2025-03-18T14:12:36Z"
}