Docs
post https://gateway.iugu.com/api/v1/transactions/charge

Autorizar e capturar em uma única requisição

Realiza autorização e captura em uma única etapa. Aceita o mesmo corpo de /authorize e segue as mesmas regras de idempotência por order_id e de recusa do adquirente (200 com payment.status nulo).

Sem ações implementadas definidas

Request

Headers

Workspace-Id

Type: string

ID do workspace. Quando ausente, é usado o workspace padrão do Gateway.

Ex: 1D81KhKbYuVq9505Bz4Nk9

Body Required

Content Type: application/json

account_id

Required

String

Identificador da conta

order_id

Required

String

Identificador do pedido. Garante idempotência e é retornado como `payment.invoice_id`.

client_ref

Required

String

Número de referência do cliente

credit_card_id

Required

String

ID do cartão de crédito tokenizado no Gateway

mcc

Required

String

Merchant Category Code (truncado para 4 caracteres)

cnpj

Required

String = 14 characters

CNPJ do estabelecimento (aceita CNPJ alfanumérico; convertido para maiúsculas)

amount_cents

Required

Integer

Valor da transação em centavos

installments

Required

Integer

Número de parcelas

soft_descriptor

Required

String

Texto que aparecerá na fatura do cartão

account_info
Object

Dados da conta repassados à análise antifraude

payment_receipt
String

Dado do comprovante repassado à análise antifraude

initiator
String

Iniciador da transação, repassado à análise antifraude

subscription_id
String

ID da assinatura. Tem precedência sobre `subscription.id`.

currency
String

Moeda da transação

extra_amount_cents
Integer

Valor adicional em centavos

fines_cents
Integer

Valor de multa em centavos

discount_cents
Integer

Valor de desconto em centavos

recurrent
Boolean

Indica se é uma transação recorrente

ip_address
String

Endereço IP do cliente

skip_anti_fraud
Boolean DEPRECATED

Ignorado; mantido apenas por compatibilidade

network_tid
String DEPRECATED

Ignorado; o encadeamento de recorrência (CIT/MIT) é resolvido pelo Gateway a partir dos pagamentos anteriores da mesma assinatura

transaction_link_id
String DEPRECATED

Ignorado; o encadeamento de recorrência (CIT/MIT) é resolvido pelo Gateway a partir dos pagamentos anteriores da mesma assinatura

site
String DEPRECATED

Ignorado; mantido apenas por compatibilidade

sub_merchant
Object

Dados do subcredenciado. Quando `document_type` é `cpf`, o MCC utilizado é definido pela configuração do workspace.

id

Required

String

ID do sub-merchant

document_type

Required

String
Enum: `cpf`, `cnpj`

Tipo do documento

document_number

Required

String [11..14] characters

Número do documento, com 11 (CPF) ou 14 (CNPJ) caracteres; convertido para maiúsculas

address

Required

String

Endereço

city

Required

String

Cidade

state

Required

String

Estado

country_code

Required

String

Código do país

postal_code

Required

String ^\d{5}-?\d{3}$

CEP (com ou sem hífen; enviado ao adquirente só com dígitos)

mcc

Required

String

Merchant Category Code (truncado para 4 caracteres)

company_name

Required

String

Nome da empresa

phone_number
String

Número de telefone

website
String

URL do site. Sem esquema, recebe o prefixo `https://`.

items
Array of objects

name

Required

String

Nome do item

type

Required

String

Tipo do item

price_cents

Required

Integer

Preço em centavos

description
String

Descrição do item

quantity
Integer

Quantidade

payer
Object

email

Required

String

Email do pagador

id
String

ID do pagador

name
String

Nome do pagador

document_number
String

Número do documento

phone_prefix
String

Prefixo do telefone

phone_number
String

Número do telefone

gender
String
Enum: `M`, `F`

Gênero

borned_at
String

Data de nascimento

created_at
String

Data de criação

address
Object

street
String

Rua

number
String

Número

district
String

Bairro

city
String

Cidade

state
String

Estado

country
String

País

postal_code
String

CEP

receiver
Object

name
String

Nome do recebedor

document_number
String

Número do documento

postal_code
String

CEP

subscription
Object

id
String

ID da assinatura

price_cents
Integer

Preço em centavos

recurrence
Integer

Recorrência em dias

started_at
String

Data de início

expires_at
String

Data de expiração

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "account_id": "<ACCOUNT_ID>",
  "order_id": "<ORDER_ID>",
  "client_ref": "<CLIENT_REF>",
  "credit_card_id": "<CREDIT_CARD_ID>",
  "mcc": "<MCC>",
  "cnpj": "<CNPJ>",
  "amount_cents": "<AMOUNT_CENTS>",
  "installments": "<INSTALLMENTS>",
  "soft_descriptor": "<SOFT_DESCRIPTOR>",
  "account_info": {
  },
  "payment_receipt": "<PAYMENT_RECEIPT>",
  "initiator": "<INITIATOR>",
  "subscription_id": "<SUBSCRIPTION_ID>",
  "currency": "<CURRENCY>",
  "extra_amount_cents": "<EXTRA_AMOUNT_CENTS>",
  "fines_cents": "<FINES_CENTS>",
  "discount_cents": "<DISCOUNT_CENTS>",
  "recurrent": "<RECURRENT>",
  "ip_address": "<IP_ADDRESS>",
  "skip_anti_fraud": "<SKIP_ANTI_FRAUD>",
  "network_tid": "<NETWORK_TID>",
  "transaction_link_id": "<TRANSACTION_LINK_ID>",
  "site": "<SITE>",
  "sub_merchant": {
    "id": "<ID>",
    "document_type": "<DOCUMENT_TYPE>",
    "document_number": "<DOCUMENT_NUMBER>",
    "address": "<ADDRESS>",
    "city": "<CITY>",
    "state": "<STATE>",
    "country_code": "<COUNTRY_CODE>",
    "postal_code": "<POSTAL_CODE>",
    "mcc": "<MCC>",
    "company_name": "<COMPANY_NAME>",
    "phone_number": "<PHONE_NUMBER>",
    "website": "<WEBSITE>"
  },
  "items": [
    {
      "name": "<NAME>",
      "type": "<TYPE>",
      "price_cents": "<PRICE_CENTS>",
      "description": "<DESCRIPTION>",
      "quantity": "<QUANTITY>"
    }
  ],
  "payer": {
    "email": "<EMAIL>",
    "id": "<ID>",
    "name": "<NAME>",
    "document_number": "<DOCUMENT_NUMBER>",
    "phone_prefix": "<PHONE_PREFIX>",
    "phone_number": "<PHONE_NUMBER>",
    "gender": "<GENDER>",
    "borned_at": "<BORNED_AT>",
    "created_at": "<CREATED_AT>",
    "address": {
      "street": "<STREET>",
      "number": "<NUMBER>",
      "district": "<DISTRICT>",
      "city": "<CITY>",
      "state": "<STATE>",
      "country": "<COUNTRY>",
      "postal_code": "<POSTAL_CODE>"
    }
  },
  "receiver": {
    "name": "<NAME>",
    "document_number": "<DOCUMENT_NUMBER>",
    "postal_code": "<POSTAL_CODE>"
  },
  "subscription": {
    "id": "<ID>",
    "price_cents": "<PRICE_CENTS>",
    "recurrence": "<RECURRENCE>",
    "started_at": "<STARTED_AT>",
    "expires_at": "<EXPIRES_AT>"
  }
}

Response

200

Pagamento processado (cobrado ou recusado pelo adquirente)

payment
Object

id
String

status
String
Enum: `authorized`, `charged`, `captured`, `partially_refunded`, `fully_refunded`, ``

Nulo quando nenhuma tentativa foi aprovada pelo adquirente

multi
Array of strings

success_ec
String

ID do estabelecimento que aprovou a transação

mcc
String

recurrent
Boolean

card_on_file
Boolean

tid
String

nsu
String

authorization_code
String

amount_cents
Integer

refunded_amount_cents
Integer

cnpj
String

workspace_id
String

account_id
String

invoice_id
String

`order_id` informado na criação do pagamento

client_ref
String

subscription_id
String

card_id
String

card_bin
String

card_last_four
String

currency
String

installments
Integer

soft_descriptor
String

created_at
String

updated_at
String

transactions
Array of objects

id
String

function
String
Enum: `authorization`, `charge`, `capture`, `cancel`

success
Boolean

tid
String

nsu
String

arp
String

acquirer
Object

payment_id
String

status_code
String

acquirer_mac_code
String

status_description
String

request_status_code
String

request_status_description
String

lr
Object

Código de retorno unificado da tentativa. Vale tanto para a recusa do adquirente quanto para a do próprio Gateway, e é o campo que substituirá `acquirer.status_code`.

code
String

Código de retorno. Da adquirente quando `source` é `acquirer`; do Gateway (`TOK01`, `MCC01`, `DEC01`…) quando é `gateway`. Vem nulo com `source` igual a `acquirer` nas transações anteriores à introdução do campo, em que o código está apenas em `acquirer.status_code`.

source
String
Enum: `acquirer`, `gateway`

Origem do código. `gateway` significa que a transação foi recusada antes de chegar ao adquirente.

card_id
String

card_bin
String

card_last_four
String

card_on_file
Boolean

transaction_token_type
String
Enum: `open`, `acquirer_token`, `network_token`, ``

Tipo de dado de cartão enviado ao adquirente

amount_cents
Integer

ec_group
Object

id
String

name
String

commercial_enterprise
Object

id
String

name
String

number
String

acquirer
String

mcc
Object

id
String

code
String

description
String

created_at
String

anti_fraud
Array of objects

Análises antifraude do pagamento, da mais recente para a mais antiga

id
String

payment_id
String

provider
String

Ex: feedzai

provider_id
String

decision
String

omniscore
String

created_at
String

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
  "payment": {
    "id": "<ID>",
    "status": "<STATUS>",
    "multi": [
      "<MULTI>"
    ],
    "success_ec": "<SUCCESS_EC>",
    "mcc": "<MCC>",
    "recurrent": "<RECURRENT>",
    "card_on_file": "<CARD_ON_FILE>",
    "tid": "<TID>",
    "nsu": "<NSU>",
    "authorization_code": "<AUTHORIZATION_CODE>",
    "amount_cents": "<AMOUNT_CENTS>",
    "refunded_amount_cents": "<REFUNDED_AMOUNT_CENTS>",
    "cnpj": "<CNPJ>",
    "workspace_id": "<WORKSPACE_ID>",
    "account_id": "<ACCOUNT_ID>",
    "invoice_id": "<INVOICE_ID>",
    "client_ref": "<CLIENT_REF>",
    "subscription_id": "<SUBSCRIPTION_ID>",
    "card_id": "<CARD_ID>",
    "card_bin": "<CARD_BIN>",
    "card_last_four": "<CARD_LAST_FOUR>",
    "currency": "<CURRENCY>",
    "installments": "<INSTALLMENTS>",
    "soft_descriptor": "<SOFT_DESCRIPTOR>",
    "created_at": "<CREATED_AT>",
    "updated_at": "<UPDATED_AT>",
    "transactions": [
      {
        "id": "<ID>",
        "function": "<FUNCTION>",
        "success": "<SUCCESS>",
        "tid": "<TID>",
        "nsu": "<NSU>",
        "arp": "<ARP>",
        "acquirer": {
          "payment_id": "<PAYMENT_ID>",
          "status_code": "<STATUS_CODE>",
          "acquirer_mac_code": "<ACQUIRER_MAC_CODE>",
          "status_description": "<STATUS_DESCRIPTION>",
          "request_status_code": "<REQUEST_STATUS_CODE>",
          "request_status_description": "<REQUEST_STATUS_DESCRIPTION>"
        },
        "lr": {
          "code": "<CODE>",
          "source": "<SOURCE>"
        },
        "card_id": "<CARD_ID>",
        "card_bin": "<CARD_BIN>",
        "card_last_four": "<CARD_LAST_FOUR>",
        "card_on_file": "<CARD_ON_FILE>",
        "transaction_token_type": "<TRANSACTION_TOKEN_TYPE>",
        "amount_cents": "<AMOUNT_CENTS>",
        "ec_group": {
          "id": "<ID>",
          "name": "<NAME>"
        },
        "commercial_enterprise": {
          "id": "<ID>",
          "name": "<NAME>",
          "number": "<NUMBER>",
          "acquirer": "<ACQUIRER>",
          "mcc": {
            "id": "<ID>",
            "code": "<CODE>",
            "description": "<DESCRIPTION>"
          }
        },
        "created_at": "<CREATED_AT>"
      }
    ],
    "anti_fraud": [
      {
        "id": "<ID>",
        "payment_id": "<PAYMENT_ID>",
        "provider": "feedzai",
        "provider_id": "<PROVIDER_ID>",
        "decision": "<DECISION>",
        "omniscore": "<OMNISCORE>",
        "created_at": "<CREATED_AT>"
      }
    ]
  }
}

400

Parâmetro obrigatório ausente, com tipo/formato inválido ou não documentado

error
String
Enum: `invalid_parameter_error`

error_code
String

`invalid_`

Ex: invalid_sub_merchant_postal_code

details
Object

message
String

Ex: sub_merchant.postal_code format is invalid

Example
1
2
3
4
5
6
7
{
  "error": "<ERROR>",
  "error_code": "invalid_sub_merchant_postal_code",
  "details": {
    "message": "sub_merchant.postal_code format is invalid"
  }
}

401

Não autorizado - Token de autenticação inválido ou ausente

message
String
Enum: `Requires authentication`, `Bad credentials`

Example
1
2
3
{
  "message": "<MESSAGE>"
}

403

`anti_fraud_unauthorized`: a análise antifraude recusou a transação (`details` traz o registro da análise)

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

404

`credit_card_not_found`: Cartão de crédito não encontrado

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

409

`payment_processing_in_progress`: outra requisição para o mesmo pagamento está em processamento; tente novamente

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

422

Requisição não processável. Possíveis causas: - `token_blocked`: o token do cartão está bloqueado por recusas anteriores - `mcc_mismatch`: o MCC informado diverge do MCC do CNPJ (quando o workspace está configurado para bloquear) - `no_active_mcc_found`: nenhum MCC ativo encontrado para o CNPJ - `serpro_unavailable`: consulta de dados do CNPJ indisponível - `payment_creation_error`: falha ao registrar o pagamento

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

500

Erro interno. Inclui falhas de roteamento (ex.: `no_ec_group_found`, `no_active_ecs_available`) e erros inesperados.

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}