# ABECS return codes (/docs/cartao/abecs-codes.en) The Brazilian Association of Credit Card and Services Companies (ABECS) defined a standard for the return codes of declined sales, covering payment solutions in both physical retail and Brazilian e-commerce. PayZu processes transactions according to this standard. See below the table with the return codes standardized by ABECS. To access the official table on the ABECS website, go to the [ABECS regulation](https://api.abecs.org.br/wp-content/uploads/2023/04/20230406-Normativo-21-V3-aprovado-publicacao.pdf). To optimize authorization performance, see the [Card network retry program](/docs/cartao/retry-program) manual and learn what action to take when a retry is allowed. The codes in the tables were separated by card network to make them easier to browse. Numbers and their definitions may repeat across different tables, so make sure to check the table for the network you are interested in. * [ABECS Elo table](#elo-network) * [ABECS Visa table](#visa-network) * [ABECS MasterCard/Hiper table](#mastercardhiper-network) * [ABECS Amex table](#amex-network) ## Elo network [#elo-network] | ABECS code | Code type | Message | POS/E-commerce message | | ---------- | ------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------- | | 4 | REVERSIBLE | REDO THE TRANSACTION (ISSUER REQUESTS RETRY) | REDO THE TRANSACTION | | 5 | REVERSIBLE | GENERIC | CONTACT YOUR CARD ISSUER | | 6 | REVERSIBLE | CHECK WITH THE ACQUIRER | MERCHANT, CONTACT THE ACQUIRER | | 12 | IRREVERSIBLE | CARD ERROR | CHECK THE CARD DATA | | 13 | IRREVERSIBLE | INVALID TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 14 or 56 | IRREVERSIBLE | CARD NUMBER DOES NOT BELONG TO THE ISSUER / INVALID CARD NUMBER | CHECK THE CARD DATA | | 19 | IRREVERSIBLE | ACQUIRER PROBLEM | CARD ERROR - DO NOT RETRY | | 23 | IRREVERSIBLE | INVALID INSTALLMENT AMOUNT | INVALID INSTALLMENT PLAN - DO NOT RETRY | | 30 | IRREVERSIBLE | FORMAT ERROR (MESSAGING) | CARD ERROR - DO NOT RETRY | | 38 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / PURCHASES | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 41 | IRREVERSIBLE | LOST CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 43 | IRREVERSIBLE | STOLEN CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 46 | IRREVERSIBLE | ACCOUNT CLOSED | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 51 | REVERSIBLE | INSUFFICIENT BALANCE/LIMIT | NOT AUTHORIZED | | 54 | IRREVERSIBLE | EXPIRED CARD / INVALID EXPIRATION DATE | CHECK THE CARD DATA | | 55 | REVERSIBLE | INVALID PIN | INVALID PIN | | 57 | IRREVERSIBLE | TRANSACTION NOT ALLOWED FOR THIS CARD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 57 | IRREVERSIBLE | TRANSACTION NOT ALLOWED BY TERMINAL CAPABILITY | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 57 | IRREVERSIBLE | CONFIRMED FRAUD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 57 | IRREVERSIBLE | TRANSACTION DENIED DUE TO LAW VIOLATION | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 58 | IRREVERSIBLE | INVALID MERCHANT | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 59 | REVERSIBLE | SUSPECTED FRAUD/TRAVEL NOTICE | CONTACT YOUR CARD ISSUER | | 61 | REVERSIBLE | AMOUNT EXCEEDED / WITHDRAWAL | AMOUNT EXCEEDED. CONTACT YOUR CARD ISSUER | | 62 | REVERSIBLE | TEMPORARY BLOCK (E.G. DELINQUENCY) | CONTACT YOUR CARD ISSUER | | 62 | IRREVERSIBLE | DOMESTIC CARD - INTERNATIONAL TRANSACTION | CARD DOES NOT ALLOW INTERNATIONAL TRANSACTIONS | | 63 | IRREVERSIBLE | SECURITY VIOLATION (INVALID OR NOT PRESENT) | CHECK THE CARD DATA | | 64 | IRREVERSIBLE | INVALID MINIMUM TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 65 | REVERSIBLE | NUMBER OF WITHDRAWALS EXCEEDED | NUMBER OF WITHDRAWALS EXCEEDED. CONTACT YOUR CARD ISSUER | | 75 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / WITHDRAWAL | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 76 | IRREVERSIBLE | INVALID OR NONEXISTENT DESTINATION ACCOUNT | INVALID DESTINATION ACCOUNT - DO NOT RETRY | | 77 | IRREVERSIBLE | INVALID OR NONEXISTENT SOURCE ACCOUNT | INVALID SOURCE ACCOUNT - DO NOT RETRY | | 78 | REVERSIBLE | NEW CARD NOT UNBLOCKED (INCLUDES CARD BLOCKED BY THE CUSTOMER IN THE APP - E-COM NFC) | UNBLOCK THE CARD | | 82 | IRREVERSIBLE | INVALID CARD (cryptogram) | CARD ERROR - DO NOT RETRY | | 83 | IRREVERSIBLE | EXPIRED PIN / PIN ENCRYPTION ERROR | INVALID PIN - DO NOT RETRY | | 91 | REVERSIBLE | ISSUER UNAVAILABLE | COMMUNICATION FAILURE - TRY AGAIN LATER | | 96 | REVERSIBLE | SYSTEM FAILURE | COMMUNICATION FAILURE - TRY AGAIN LATER | | AB | REVERSIBLE | INCORRECT FUNCTION (DEBIT) | USE THE CREDIT FUNCTION | | AC | REVERSIBLE | INCORRECT FUNCTION (CREDIT) | USE THE DEBIT FUNCTION | | FM | IRREVERSIBLE | USE THE CHIP | USE THE CHIP | | P5 | IRREVERSIBLE | PIN CHANGE / UNBLOCK | INVALID PIN - DO NOT RETRY | | P6 | REVERSIBLE | NEW PIN NOT ACCEPTED | INVALID PIN USE THE NEW PIN | ## Visa network [#visa-network] | ABECS code | Code type | Message | POS/E-commerce message | | ---------- | ------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | 3 | IRREVERSIBLE | INVALID MERCHANT | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 4 | IRREVERSIBLE | PICK UP CARD | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 5 | REVERSIBLE | GENERIC | CONTACT YOUR CARD ISSUER | | 6 | IRREVERSIBLE | CARD ERROR | CHECK THE CARD DATA | | 7 | IRREVERSIBLE | CONFIRMED FRAUD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 12 | IRREVERSIBLE | FORMAT ERROR (MESSAGING) | CARD ERROR - DO NOT RETRY | | 13 | IRREVERSIBLE | INVALID TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 14 | IRREVERSIBLE | CARD NUMBER DOES NOT BELONG TO THE ISSUER / INVALID CARD NUMBER | CHECK THE CARD DATA | | 15 | IRREVERSIBLE | ISSUER NOT FOUND - INCORRECT BIN (acquirer decline) | INVALID CARD DATA - DO NOT RETRY | | 19 | IRREVERSIBLE | ACQUIRER PROBLEM | CARD ERROR - DO NOT RETRY | | 39 | REVERSIBLE | INCORRECT FUNCTION (CREDIT) | USE THE DEBIT FUNCTION | | 41 | IRREVERSIBLE | LOST CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 43 | IRREVERSIBLE | STOLEN CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 46 | IRREVERSIBLE | ACCOUNT CLOSED | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 51 | REVERSIBLE | INSUFFICIENT BALANCE/LIMIT | NOT AUTHORIZED | | 54 | IRREVERSIBLE | EXPIRED CARD / INVALID EXPIRATION DATE | CHECK THE CARD DATA | | 57 | IRREVERSIBLE | TRANSACTION NOT ALLOWED FOR THIS CARD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 58 | IRREVERSIBLE | TRANSACTION NOT ALLOWED BY TERMINAL CAPABILITY | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 59 | REVERSIBLE | SUSPECTED FRAUD/TRAVEL NOTICE | CONTACT YOUR CARD ISSUER | | 62 | REVERSIBLE | TEMPORARY BLOCK (E.G. DELINQUENCY) | CONTACT YOUR CARD ISSUER | | 62 | REVERSIBLE | DOMESTIC CARD - INTERNATIONAL TRANSACTION | CARD DOES NOT ALLOW INTERNATIONAL TRANSACTIONS | | 64 | IRREVERSIBLE | NON-COMPLIANCE WITH ANTI-MONEY LAUNDERING LAWS | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 65 | REVERSIBLE | NUMBER OF WITHDRAWALS EXCEEDED | NUMBER OF WITHDRAWALS EXCEEDED. CONTACT YOUR CARD ISSUER | | 75 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / PURCHASES | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 75 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / WITHDRAWAL | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 76 | IRREVERSIBLE | INVALID REVERSAL | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 78 | REVERSIBLE | NEW CARD NOT UNBLOCKED (INCLUDES CARD BLOCKED BY THE CUSTOMER IN THE APP - E-COM NFC) | UNBLOCK THE CARD | | 82 | IRREVERSIBLE | INVALID CARD (cryptogram) | CARD ERROR - DO NOT RETRY | | 91 | REVERSIBLE | ISSUER UNAVAILABLE | COMMUNICATION FAILURE - TRY AGAIN LATER | | 92 | IRREVERSIBLE | NOT FOUND BY THE ROUTER | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 93 | IRREVERSIBLE | TRANSACTION DENIED DUE TO LAW VIOLATION | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 94 | IRREVERSIBLE | DUPLICATE TRACING DATA VALUE | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 96 | REVERSIBLE | SYSTEM FAILURE | COMMUNICATION FAILURE - TRY AGAIN LATER | | 52 or 53 | REVERSIBLE | INCORRECT FUNCTION (DEBIT) | USE THE CREDIT FUNCTION | | 55 or 86 | REVERSIBLE | INVALID PIN | INVALID PIN | | 61 or N4 | REVERSIBLE | AMOUNT EXCEEDED / WITHDRAWAL | AMOUNT EXCEEDED. CONTACT YOUR CARD ISSUER | | 6P | IRREVERSIBLE | ID VALIDATION FAILURE | ID VERIFICATION FAILED | | 74 or 81 | IRREVERSIBLE | EXPIRED PIN / PIN ENCRYPTION ERROR | INVALID PIN - DO NOT RETRY | | B1 | REVERSIBLE | SURCHARGE NOT SUPPORTED | CONTACT YOUR CARD ISSUER | | B2 | REVERSIBLE | SURCHARGE NOT SUPPORTED BY THE DEBIT NETWORK | CONTACT YOUR CARD ISSUER | | N0 | REVERSIBLE | FORCE STIP | CONTACT YOUR CARD ISSUER | | N3 | IRREVERSIBLE | WITHDRAWAL NOT AVAILABLE | WITHDRAWAL NOT AVAILABLE - DO NOT RETRY | | N7 | IRREVERSIBLE | SECURITY VIOLATION (INVALID OR NOT PRESENT) | CHECK THE CARD DATA | | N7 | IRREVERSIBLE | DYNAMIC KEY CHANGE ERROR | CARD ERROR - DO NOT RETRY | | N8 | IRREVERSIBLE | DIFFERENCE - PRE AUTHORIZATION | AMOUNT DIFFERENT FROM THE PRE AUTHORIZATION - DO NOT RETRY | | R0 | IRREVERSIBLE | RECURRING PAYMENT SUSPENSION FOR A SERVICE | RECURRING PAYMENT SUSPENSION FOR SERVICE - DO NOT RETRY | | R1 | IRREVERSIBLE | RECURRING PAYMENT SUSPENSION FOR ALL SERVICES | RECURRING PAYMENT SUSPENSION FOR SERVICE - DO NOT RETRY | | R2 | IRREVERSIBLE | TRANSACTION NOT QUALIFIED FOR VISA PIN | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | R3 | IRREVERSIBLE | SUSPENSION OF ALL AUTHORIZATION ORDERS | RECURRING PAYMENT SUSPENSION FOR SERVICE - DO NOT RETRY | New retry codes for Visa: 5C and 9G. Codes 5C and 9G are new decline codes from the Visa network. See the complete retry rules for these codes in the [Card network retry program](/docs/cartao/retry-program). ## Mastercard/Hiper network [#mastercardhiper-network] | ABECS code | Code type | Message | POS/E-commerce message | | ---------- | ------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------- | | 3 | IRREVERSIBLE | INVALID MERCHANT | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 4 | IRREVERSIBLE | PICK UP CARD | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 4 | IRREVERSIBLE | CONFIRMED FRAUD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 5 | REVERSIBLE | GENERIC | CONTACT YOUR CARD ISSUER | | 12 | IRREVERSIBLE | INVALID INSTALLMENT AMOUNT | INVALID INSTALLMENT PLAN - DO NOT RETRY | | 13 | IRREVERSIBLE | INVALID TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 13 | IRREVERSIBLE | INVALID MINIMUM TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 14 or 1 | IRREVERSIBLE | CARD NUMBER DOES NOT BELONG TO THE ISSUER / INVALID CARD NUMBER | CHECK THE CARD DATA | | 15 | IRREVERSIBLE | ISSUER NOT FOUND - INCORRECT BIN (acquirer decline) | INVALID CARD DATA - DO NOT RETRY | | 30 | IRREVERSIBLE | ACQUIRER PROBLEM | CARD ERROR - DO NOT RETRY | | 30 | IRREVERSIBLE | FORMAT ERROR (MESSAGING) | CARD ERROR - DO NOT RETRY | | 41 | IRREVERSIBLE | LOST CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 43 | IRREVERSIBLE | STOLEN CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 51 | REVERSIBLE | INSUFFICIENT BALANCE/LIMIT | NOT AUTHORIZED | | 54 | IRREVERSIBLE | EXPIRED CARD / INVALID EXPIRATION DATE | CHECK THE CARD DATA | | 55 | REVERSIBLE | INVALID PIN | INVALID PIN | | 55 | REVERSIBLE | NEW PIN NOT ACCEPTED | INVALID PIN USE THE NEW PIN | | 57 | REVERSIBLE | TRANSACTION NOT ALLOWED FOR THIS CARD | TRANSACTION NOT ALLOWED FOR THIS CARD | | 57 | REVERSIBLE | TEMPORARY BLOCK (E.G. DELINQUENCY) | CONTACT YOUR CARD ISSUER | | 57 | REVERSIBLE | NEW CARD NOT UNBLOCKED (INCLUDES CARD BLOCKED BY THE CUSTOMER IN THE APP - E-COM NFC) | UNBLOCK THE CARD | | 58 | IRREVERSIBLE | TRANSACTION NOT ALLOWED BY TERMINAL CAPABILITY | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 61 | REVERSIBLE | AMOUNT EXCEEDED / WITHDRAWAL | AMOUNT EXCEEDED. CONTACT YOUR CARD ISSUER | | 62 | IRREVERSIBLE | DOMESTIC CARD - INTERNATIONAL TRANSACTION | CARD DOES NOT ALLOW INTERNATIONAL TRANSACTIONS | | 62 | IRREVERSIBLE | TRANSACTION DENIED DUE TO LAW VIOLATION | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 62 | IRREVERSIBLE | ACCOUNT CLOSED | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 63 | REVERSIBLE | SECURITY VIOLATION (INVALID OR NOT PRESENT) | CHECK THE CARD DATA | | 63 | REVERSIBLE | SUSPECTED FRAUD/TRAVEL NOTICE | CONTACT YOUR CARD ISSUER | | 65 | REVERSIBLE | NUMBER OF WITHDRAWALS EXCEEDED | NUMBER OF WITHDRAWALS EXCEEDED. CONTACT YOUR CARD ISSUER | | 75 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / WITHDRAWAL | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 88 | IRREVERSIBLE | EXPIRED PIN / PIN ENCRYPTION ERROR | INVALID PIN - DO NOT RETRY | | 88 | IRREVERSIBLE | INVALID CARD (cryptogram) | CARD ERROR - DO NOT RETRY | | 91 | REVERSIBLE | ISSUER UNAVAILABLE | COMMUNICATION FAILURE - TRY AGAIN LATER | | 92 | IRREVERSIBLE | NOT FOUND BY THE ROUTER | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 94 | IRREVERSIBLE | DUPLICATE TRACING DATA VALUE | CONTACT YOUR CARD ISSUER - DO NOT RETRY | | 96 | REVERSIBLE | SYSTEM FAILURE | COMMUNICATION FAILURE - TRY AGAIN LATER | ## Amex network [#amex-network] | ABECS code | AMEX to PayZu mapping | Code type | Message | POS/E-commerce message | | :--------- | :-------------------- | :----------- | :-------------------------------------------------------------- | :--------------------------------------------------- | | 100 | FA | REVERSIBLE | GENERIC | CONTACT YOUR CARD ISSUER | | 100 | FA | REVERSIBLE | SUSPECTED FRAUD/TRAVEL NOTICE | CONTACT YOUR CARD ISSUER | | 101 | BV | IRREVERSIBLE | EXPIRED CARD / INVALID EXPIRATION DATE | CHECK THE CARD DATA | | 106 | A4 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / PURCHASES | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 106 | A4 | REVERSIBLE | PIN ATTEMPTS EXCEEDED / WITHDRAWAL | PIN ATTEMPTS EXCEEDED. CONTACT YOUR CARD ISSUER | | 109 | DA | IRREVERSIBLE | INVALID MERCHANT | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 110 | JB | IRREVERSIBLE | INVALID TRANSACTION AMOUNT | TRANSACTION AMOUNT NOT ALLOWED - DO NOT RETRY | | 115 | A2 | IRREVERSIBLE | CARD ERROR | CHECK THE CARD DATA | | 115 | A2 | IRREVERSIBLE | INVALID INSTALLMENT AMOUNT | INVALID INSTALLMENT PLAN - DO NOT RETRY | | 116 | A5 | REVERSIBLE | INSUFFICIENT BALANCE/LIMIT | NOT AUTHORIZED | | 117 | A6 | REVERSIBLE | INVALID PIN | INVALID PIN | | 121 | A5 | REVERSIBLE | INSUFFICIENT BALANCE/LIMIT | NOT AUTHORIZED | | 122 | 8 | IRREVERSIBLE | CARD NUMBER DOES NOT BELONG TO THE ISSUER / INVALID CARD NUMBER | CHECK THE CARD DATA | | 122 | 8 | IRREVERSIBLE | SECURITY VIOLATION (INVALID OR NOT PRESENT) | CHECK THE CARD DATA | | 180 | A7 | IRREVERSIBLE | EXPIRED PIN / PIN ENCRYPTION ERROR | INVALID PIN - DO NOT RETRY | | 180 | A7 | IRREVERSIBLE | INVALID CARD (cryptogram) | CARD ERROR - DO NOT RETRY | | 181 | A3 | IRREVERSIBLE | FORMAT ERROR (MESSAGING) | CARD ERROR - DO NOT RETRY | | 200 | N/A | IRREVERSIBLE | TRANSACTION NOT ALLOWED FOR THIS CARD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 200 | FD | IRREVERSIBLE | LOST CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 200 | FD | IRREVERSIBLE | STOLEN CARD | TRANSACTION NOT ALLOWED - DO NOT RETRY | | 200 | FD | IRREVERSIBLE | CONFIRMED FRAUD | TRANSACTION NOT ALLOWED FOR THIS CARD - DO NOT RETRY | | 911 | AE | REVERSIBLE | SYSTEM FAILURE | COMMUNICATION FAILURE - TRY AGAIN LATER | | 912 | A1 | REVERSIBLE | ISSUER UNAVAILABLE | COMMUNICATION FAILURE - TRY AGAIN LATER | # Códigos de retorno ABECS (/docs/cartao/abecs-codes) A Associação Brasileira das Empresas de Cartões de Crédito e Serviços (ABECS) definiu uma padronização para os códigos de retorno em casos de vendas recusadas, abrangendo tanto soluções de pagamento no varejo físico quanto no e-commerce brasileiro. A PayZu processa as transações conforme esse padrão. Confira abaixo a tabela com os códigos de retorno padronizados pela ABECS. Para acessar a tabela oficial no site da ABECS, vá para o [Normativo ABECS](https://api.abecs.org.br/wp-content/uploads/2023/04/20230406-Normativo-21-V3-aprovado-publicacao.pdf). Para otimizar a performance nas autorizações, consulte o manual do [Programa de retentativa das bandeiras](/docs/cartao/retry-program) e saiba qual ação tomar caso a retentativa seja permitida. Os códigos na tabela foram separados por bandeira para facilitar a visualização. Os números e suas definições podem se repetir em diferentes tabelas, tenha atenção em consultar a tabela da bandeira de interesse. * [Tabela ABECS Elo](#bandeira-elo) * [Tabela ABECS Visa](#bandeira-visa) * [Tabela ABECS MasterCard/Hiper](#bandeira-mastercardhiper) * [Tabela ABECS Amex](#bandeira-amex) ## Bandeira Elo [#bandeira-elo] | Código ABECS | Tipo de código | Mensagem | Mensagem POS/E-commerce | | ------------ | -------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | 4 | REVERSÍVEL | REFAZER A TRANSAÇÃO (EMISSOR SOLICITA RETENTATIVA) | REFAZER A TRANSAÇÃO | | 5 | REVERSÍVEL | GENÉRICA | CONTATE A CENTRAL DO SEU CARTÃO | | 6 | REVERSÍVEL | CONSULTAR CREDENCIADOR | LOJISTA, CONTATE O ADQUIRENTE | | 12 | IRREVERSÍVEL | ERRO NO CARTÃO | VERIFIQUE OS DADOS DO CARTÃO | | 13 | IRREVERSÍVEL | VALOR DA TRANSAÇÃO INVÁLIDA | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 14 ou 56 | IRREVERSÍVEL | NÚMERO CARTÃO NÃO PERTENCE AO EMISSOR / NÚMERO CARTÃO INVÁLIDO | VERIFIQUE OS DADOS DO CARTÃO | | 19 | IRREVERSÍVEL | PROBLEMA NO ADQUIRENTE | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 23 | IRREVERSÍVEL | VALOR DA PARCELA INVÁLIDA | PARCELAMENTO INVÁLIDO - NÃO TENTE NOVAMENTE | | 30 | IRREVERSÍVEL | ERRO DE FORMATO (MENSAGERIA) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 38 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA / COMPRAS | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 41 | IRREVERSÍVEL | CARTÃO PERDIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 43 | IRREVERSÍVEL | CARTÃO ROUBADO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 46 | IRREVERSÍVEL | CONTA ENCERRADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 51 | REVERSÍVEL | SALDO/LIMITE INSUFICIENTE | NÃO AUTORIZADA | | 54 | IRREVERSÍVEL | CARTÃO VENCIDO / DT EXPIRAÇÃO INVÁLIDA | VERIFIQUE OS DADOS DO CARTÃO | | 55 | REVERSÍVEL | SENHA INVÁLIDA | SENHA INVÁLIDA | | 57 | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 57 | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA CAPACIDADE DO TERMINAL | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 57 | IRREVERSÍVEL | FRAUDE CONFIRMADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 57 | IRREVERSÍVEL | TRANSAÇÃO NEGADA POR INFRAÇÃO DE LEI | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 58 | IRREVERSÍVEL | COMERCIANTE INVÁLIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 59 | REVERSÍVEL | SUSPEITA DE FRAUDE/AVISO DE VIAGEM | CONTATE A CENTRAL DO SEU CARTÃO | | 61 | REVERSÍVEL | VALOR EXCESSO / SAQUE | VALOR EXCEDIDO. CONTATE A CENTRAL DO SEU CARTÃO | | 62 | REVERSÍVEL | BLOQUEIO TEMPORÁRIO (EX: INADIMPLÊNCIA) | CONTATE A CENTRAL DO SEU CARTÃO | | 62 | IRREVERSÍVEL | CARTÃO DOMÉSTICO - TRANSAÇÃO INTERNACIONAL | CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL | | 63 | IRREVERSÍVEL | VIOLAÇÃO DE SEGURANÇA (INVÁLIDO OU NÃO PRESENTE) | VERIFIQUE OS DADOS DO CARTÃO | | 64 | IRREVERSÍVEL | VALOR MÍNIMO DA TRANSAÇÃO INVÁLIDO | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 65 | REVERSÍVEL | QUANT. DE SAQUES EXCEDIDO | QUANTIDADE DE SAQUES EXCEDIDA. CONTATE A CENTRAL DO SEU CARTÃO | | 75 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA/ SAQUE | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 76 | IRREVERSÍVEL | CONTA DESTINO INVÁLIDA OU INEXISTENTE | CONTA DESTINO INVÁLIDA - NÃO TENTE NOVAMENTE | | 77 | IRREVERSÍVEL | CONTA ORIGEM INVÁLIDA OU INEXISTENTE | CONTA ORIGEM INVÁLIDA - NÃO TENTE NOVAMENTE | | 78 | REVERSÍVEL | CARTÃO NOVO SEM DESBLOQUEIO (INCLUI CARTÃO BLOQUEADO PELO CLIENTE NO APLICATIVO - E-COM NFC) | DESBLOQUEIE O CARTÃO | | 82 | IRREVERSÍVEL | CARTÃO INVÁLIDO (criptograma) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 83 | IRREVERSÍVEL | SENHA VENCIDA / ERRO DE CRIPTOGRAFIA DE SENHA | SENHA INVÁLIDA - NÃO TENTE NOVAMENTE | | 91 | REVERSÍVEL | EMISSOR FORA DO AR | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | 96 | REVERSÍVEL | FALHA DO SISTEMA | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | AB | REVERSÍVEL | FUNÇÃO INCORRETA (DÉBITO) | UTILIZE FUNÇÃO CRÉDITO | | AC | REVERSÍVEL | FUNÇÃO INCORRETA (CRÉDITO) | UTILIZE FUNÇÃO DÉBITO | | FM | IRREVERSÍVEL | UTILIZAR O CHIP | UTILIZE O CHIP | | P5 | IRREVERSÍVEL | TROCA DE SENHA / DESBLOQUEIO | SENHA INVÁLIDA - NÃO TENTE NOVAMENTE | | P6 | REVERSÍVEL | NOVA SENHA NÃO ACEITA | SENHA INVÁLIDA UTILIZE A NOVA SENHA | ## Bandeira Visa [#bandeira-visa] | Código ABECS | Tipo de código | Mensagem | Mensagem POS/E-commerce | | ------------ | -------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | 3 | IRREVERSÍVEL | COMERCIANTE INVÁLIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 4 | IRREVERSÍVEL | RECOLHER CARTÃO | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 5 | REVERSÍVEL | GENÉRICA | CONTATE A CENTRAL DO SEU CARTÃO | | 6 | IRREVERSÍVEL | ERRO NO CARTÃO | VERIFIQUE OS DADOS DO CARTÃO | | 7 | IRREVERSÍVEL | FRAUDE CONFIRMADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 12 | IRREVERSÍVEL | ERRO DE FORMATO (MENSAGERIA) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 13 | IRREVERSÍVEL | VALOR DA TRANSAÇÃO INVÁLIDA | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 14 | IRREVERSÍVEL | NÚMERO CARTÃO NÃO PERTENCE AO EMISSOR / NÚMERO CARTÃO INVÁLIDO | VERIFIQUE OS DADOS DO CARTÃO | | 15 | IRREVERSÍVEL | EMISSOR Ñ LOCALIZADO - BIN INCORRETO (negativa do adquirente) | DADOS DO CARTÃO INVÁLIDO - NÃO TENTE NOVAMENTE | | 19 | IRREVERSÍVEL | PROBLEMA NO ADQUIRENTE | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 39 | REVERSÍVEL | FUNÇÃO INCORRETA (CRÉDITO) | UTILIZE FUNÇÃO DÉBITO | | 41 | IRREVERSÍVEL | CARTÃO PERDIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 43 | IRREVERSÍVEL | CARTÃO ROUBADO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 46 | IRREVERSÍVEL | CONTA ENCERRADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 51 | REVERSÍVEL | SALDO/LIMITE INSUFICIENTE | NÃO AUTORIZADA | | 54 | IRREVERSÍVEL | CARTÃO VENCIDO / DT EXPIRAÇÃO INVÁLIDA | VERIFIQUE OS DADOS DO CARTÃO | | 57 | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 58 | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA CAPACIDADE DO TERMINAL | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 59 | REVERSÍVEL | SUSPEITA DE FRAUDE/AVISO DE VIAGEM | CONTATE A CENTRAL DO SEU CARTÃO | | 62 | REVERSÍVEL | BLOQUEIO TEMPORÁRIO (EX: INADIMPLÊNCIA) | CONTATE A CENTRAL DO SEU CARTÃO | | 62 | REVERSÍVEL | CARTÃO DOMÉSTICO - TRANSAÇÃO INTERNACIONAL | CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL | | 64 | IRREVERSÍVEL | NÃO CUMPRIMENTO PELAS LEIS DE ANTE LAVAGEM DE DINHEIRO | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 65 | REVERSÍVEL | QUANT. DE SAQUES EXCEDIDO | QUANTIDADE DE SAQUES EXCEDIDA. CONTATE A CENTRAL DO SEU CARTÃO | | 75 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA / COMPRAS | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 75 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA/ SAQUE | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 76 | IRREVERSÍVEL | REVERSÃO INVÁLIDA | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 78 | REVERSÍVEL | CARTÃO NOVO SEM DESBLOQUEIO (INCLUI CARTÃO BLOQUEADO PELO CLIENTE NO APLICATIVO - E-COM NFC) | DESBLOQUEIE O CARTÃO | | 82 | IRREVERSÍVEL | CARTÃO INVÁLIDO (criptograma) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 91 | REVERSÍVEL | EMISSOR FORA DO AR | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | 92 | IRREVERSÍVEL | NÃO LOCALIZADO PELO ROTEADOR | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 93 | IRREVERSÍVEL | TRANSAÇÃO NEGADA POR INFRAÇÃO DE LEI | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 94 | IRREVERSÍVEL | VALOR DO TRACING DATA DUPLICADO | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTENOVAMENTE | | 96 | REVERSÍVEL | FALHA DO SISTEMA | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | 52 ou 53 | REVERSÍVEL | FUNÇÃO INCORRETA (DÉBITO) | UTILIZE FUNÇÃO CRÉDITO | | 55 ou 86 | REVERSÍVEL | SENHA INVÁLIDA | SENHA INVÁLIDA | | 61 ou N4 | REVERSÍVEL | VALOR EXCESSO / SAQUE | VALOR EXCEDIDO. CONTATE A CENTRAL DO SEU CARTÃO | | 6P | IRREVERSÍVEL | FALHA VALIDAÇÃO DE ID | FALHA NA VERIFICAÇÃO DO ID | | 74 ou 81 | IRREVERSÍVEL | SENHA VENCIDA / ERRO DE CRIPTOGRAFIA DE SENHA | SENHA INVÁLIDA - NÃO TENTE NOVAMENTE | | B1 | REVERSÍVEL | SURCHARGE NÃO SUPORTADO | CONTATE A CENTRAL DO SEU CARTÃO | | B2 | REVERSÍVEL | SURCHARGE NÃO SUPORTADO PELA REDE DE DÉBITO | CONTATE A CENTRAL DO SEU CARTÃO | | N0 | REVERSÍVEL | FORÇAR STIP | CONTATE A CENTRAL DO SEU CARTÃO | | N3 | IRREVERSÍVEL | SAQUE NÃO DISPONÍVEL | SAQUE NÃO DISPONÍVEL - NÃO TENTE NOVAMENTE | | N7 | IRREVERSÍVEL | VIOLAÇÃO DE SEGURANÇA (INVÁLIDO OU NÃO PRESENTE) | VERIFIQUE OS DADOS DO CARTÃO | | N7 | IRREVERSÍVEL | ERRO POR MUDANÇA DE CHAVE DINÂMICA | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | N8 | IRREVERSÍVEL | DIFERENÇA - PRÉ AUTORIZAÇÃO | VALOR DIFERENTE DA PRÉ AUTORIZAÇÃO - NÃO TENTE NOVAMENTE | | R0 | IRREVERSÍVEL | SUSPENSÃO DE PAGAMENTO RECORRENTE PARA UM SERVIÇO | SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE | | R1 | IRREVERSÍVEL | SUSPENSÃO DE PAGAMENTO RECORRENTE PARA TODOS SERVIÇO | SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE | | R2 | IRREVERSÍVEL | TRANSAÇÃO NÃO QUALIFICADA PARA VISA PIN | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | R3 | IRREVERSÍVEL | SUSPENSÃO DE TODAS AS ORDENS DE AUTORIZAÇÃO | SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE | Novos códigos de retentativa para a Visa: 5C e 9G. Os códigos 5C e 9G são novos códigos de negativa da bandeira Visa. Consulte as regras completas para a retentativa desses códigos no [Programa de retentativa das bandeiras](/docs/cartao/retry-program). ## Bandeira Mastercard/Hiper [#bandeira-mastercardhiper] | Código ABECS | Tipo de código | Mensagem | Mensagem POS/E-commerce | | ------------ | -------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | 3 | IRREVERSÍVEL | COMERCIANTE INVÁLIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 4 | IRREVERSÍVEL | RECOLHER CARTÃO | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 4 | IRREVERSÍVEL | FRAUDE CONFIRMADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 5 | REVERSÍVEL | GENÉRICA | CONTATE A CENTRAL DO SEU CARTÃO | | 12 | IRREVERSÍVEL | VALOR DA PARCELA INVÁLIDA | PARCELAMENTO INVÁLIDO - NÃO TENTE NOVAMENTE | | 13 | IRREVERSÍVEL | VALOR DA TRANSAÇÃO INVÁLIDA | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 13 | IRREVERSÍVEL | VALOR MÍNIMO DA TRANSAÇÃO INVÁLIDO | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 14 ou 1 | IRREVERSÍVEL | NÚMERO CARTÃO NÃO PERTENCE AO EMISSOR / NÚMERO CARTÃO INVÁLIDO | VERIFIQUE OS DADOS DO CARTÃO | | 15 | IRREVERSÍVEL | EMISSOR Ñ LOCALIZADO - BIN INCORRETO (negativa do adquirente) | DADOS DO CARTÃO INVÁLIDO - NÃO TENTE NOVAMENTE | | 30 | IRREVERSÍVEL | PROBLEMA NO ADQUIRENTE | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 30 | IRREVERSÍVEL | ERRO DE FORMATO (MENSAGERIA) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 41 | IRREVERSÍVEL | CARTÃO PERDIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 43 | IRREVERSÍVEL | CARTÃO ROUBADO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 51 | REVERSÍVEL | SALDO/LIMITE INSUFICIENTE | NÃO AUTORIZADA | | 54 | IRREVERSÍVEL | CARTÃO VENCIDO / DT EXPIRAÇÃO INVÁLIDA | VERIFIQUE OS DADOS DO CARTÃO | | 55 | REVERSÍVEL | SENHA INVÁLIDA | SENHA INVÁLIDA | | 55 | REVERSÍVEL | NOVA SENHA NÃO ACEITA | SENHA INVÁLIDA UTILIZE A NOVA SENHA | | 57 | REVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | | 57 | REVERSÍVEL | BLOQUEIO TEMPORÁRIO (EX: INADIMPLÊNCIA) | CONTATE A CENTRAL DO SEU CARTÃO | | 57 | REVERSÍVEL | CARTÃO NOVO SEM DESBLOQUEIO (INCLUI CARTÃO BLOQUEADO PELO CLIENTE NO APLICATIVO - E-COM NFC) | DESBLOQUEIE O CARTÃO | | 58 | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA CAPACIDADE DO TERMINAL | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 61 | REVERSÍVEL | VALOR EXCESSO / SAQUE | VALOR EXCEDIDO. CONTATE A CENTRAL DO SEU CARTÃO | | 62 | IRREVERSÍVEL | CARTÃO DOMÉSTICO - TRANSAÇÃO INTERNACIONAL | CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL | | 62 | IRREVERSÍVEL | TRANSAÇÃO NEGADA POR INFRAÇÃO DE LEI | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 62 | IRREVERSÍVEL | CONTA ENCERRADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 63 | REVERSÍVEL | VIOLAÇÃO DE SEGURANÇA (INVÁLIDO OU NÃO PRESENTE) | VERIFIQUE OS DADOS DO CARTÃO | | 63 | REVERSÍVEL | SUSPEITA DE FRAUDE/AVISO DE VIAGEM | CONTATE A CENTRAL DO SEU CARTÃO | | 65 | REVERSÍVEL | QUANT. DE SAQUES EXCEDIDO | QUANTIDADE DE SAQUES EXCEDIDA. CONTATE A CENTRAL DO SEU CARTÃO | | 75 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA/ SAQUE | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 88 | IRREVERSÍVEL | SENHA VENCIDA / ERRO DE CRIPTOGRAFIA DE SENHA | SENHA INVÁLIDA - NÃO TENTE NOVAMENTE | | 88 | IRREVERSÍVEL | CARTÃO INVÁLIDO (criptograma) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 91 | REVERSÍVEL | EMISSOR FORA DO AR | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | 92 | IRREVERSÍVEL | NÃO LOCALIZADO PELO ROTEADOR | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE | | 94 | IRREVERSÍVEL | VALOR DO TRACING DATA DUPLICADO | CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTENOVAMENTE | | 96 | REVERSÍVEL | FALHA DO SISTEMA | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | ## Bandeira Amex [#bandeira-amex] | Código ABECS | AMEX - De/Para PayZu | Tipo de código | Mensagem | Mensagem POS/E-commerce | | :----------- | :------------------- | :------------- | :------------------------------------------------------------- | :------------------------------------------------------------ | | 100 | FA | REVERSÍVEL | GENÉRICA | CONTATE A CENTRAL DO SEU CARTÃO | | 100 | FA | REVERSÍVEL | SUSPEITA DE FRAUDE/AVISO DE VIAGEM | CONTATE A CENTRAL DO SEU CARTÃO | | 101 | BV | IRREVERSÍVEL | CARTÃO VENCIDO / DT EXPIRAÇÃO INVÁLIDA | VERIFIQUE OS DADOS DO CARTÃO | | 106 | A4 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA / COMPRAS | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 106 | A4 | REVERSÍVEL | EXCEDIDAS TENTATIVAS DE SENHA/ SAQUE | EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO | | 109 | DA | IRREVERSÍVEL | COMERCIANTE INVÁLIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 110 | JB | IRREVERSÍVEL | VALOR DA TRANSAÇÃO INVÁLIDA | VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE | | 115 | A2 | IRREVERSÍVEL | ERRO NO CARTÃO | VERIFIQUE OS DADOS DO CARTÃO | | 115 | A2 | IRREVERSÍVEL | VALOR DA PARCELA INVÁLIDA | PARCELAMENTO INVÁLIDO - NÃO TENTE NOVAMENTE | | 116 | A5 | REVERSÍVEL | SALDO/LIMITE INSUFICIENTE | NÃO AUTORIZADA | | 117 | A6 | REVERSÍVEL | SENHA INVÁLIDA | SENHA INVÁLIDA | | 121 | A5 | REVERSÍVEL | SALDO/LIMITE INSUFICIENTE | NÃO AUTORIZADA | | 122 | 8 | IRREVERSÍVEL | NÚMERO CARTÃO NÃO PERTENCE AO EMISSOR / NÚMERO CARTÃO INVÁLIDO | VERIFIQUE OS DADOS DO CARTÃO | | 122 | 8 | IRREVERSÍVEL | VIOLAÇÃO DE SEGURANÇA (INVÁLIDO OU NÃO PRESENTE) | VERIFIQUE OS DADOS DO CARTÃO | | 180 | A7 | IRREVERSÍVEL | SENHA VENCIDA / ERRO DE CRIPTOGRAFIA DE SENHA | SENHA INVÁLIDA - NÃO TENTE NOVAMENTE | | 180 | A7 | IRREVERSÍVEL | CARTÃO INVÁLIDO (criptograma) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 181 | A3 | IRREVERSÍVEL | ERRO DE FORMATO (MENSAGERIA) | ERRO NO CARTÃO - NÃO TENTE NOVAMENTE | | 200 | N/A | IRREVERSÍVEL | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 200 | FD | IRREVERSÍVEL | CARTÃO PERDIDO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 200 | FD | IRREVERSÍVEL | CARTÃO ROUBADO | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | 200 | FD | IRREVERSÍVEL | FRAUDE CONFIRMADA | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | 911 | AE | REVERSÍVEL | FALHA DO SISTEMA | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | | 912 | A1 | REVERSÍVEL | EMISSOR FORA DO AR | FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE | # ABECS 返回码 (/docs/cartao/abecs-codes.zh) 巴西信用卡与服务企业协会(ABECS)为拒绝交易的返回码制定了统一标准,覆盖巴西线下零售支付方案和电商场景。 PayZu 按照该标准处理交易。请查阅下方 ABECS 标准化返回码表格。 如需查看 ABECS 官网的官方表格,请访问 [ABECS 官方规范](https://api.abecs.org.br/wp-content/uploads/2023/04/20230406-Normativo-21-V3-aprovado-publicacao.pdf)。 为优化授权成功率,请查阅[卡组织重试计划](/docs/cartao/retry-program)手册,了解在允许重试时应采取的措施。 表格已按卡组织分列,便于查阅。相同的代码及其定义可能出现在不同的表格中,请注意查阅目标卡组织对应的表格。 * [Elo 卡组织 ABECS 表](#elo-卡组织) * [Visa 卡组织 ABECS 表](#visa-卡组织) * [MasterCard/Hiper 卡组织 ABECS 表](#mastercardhiper-卡组织) * [Amex 卡组织 ABECS 表](#amex-卡组织) ## Elo 卡组织 [#elo-卡组织] | ABECS 代码 | 代码类型 | 消息 | POS/电商消息 | | -------- | ---- | ----------------------------- | ----------------- | | 4 | 可逆 | 重新发起交易(发卡行要求重试) | 重新发起交易 | | 5 | 可逆 | 通用拒绝 | 请联系发卡行客服 | | 6 | 可逆 | 咨询收单机构 | 商户请联系收单机构 | | 12 | 不可逆 | 卡片错误 | 请核对卡片信息 | | 13 | 不可逆 | 交易金额无效 | 交易金额不允许,请勿重试 | | 14 或 56 | 不可逆 | 卡号不属于该发卡行/卡号无效 | 请核对卡片信息 | | 19 | 不可逆 | 收单机构故障 | 卡片错误,请勿重试 | | 23 | 不可逆 | 分期金额无效 | 分期方案无效,请勿重试 | | 30 | 不可逆 | 报文格式错误 | 卡片错误,请勿重试 | | 38 | 可逆 | 密码尝试次数超限/消费 | 密码尝试次数超限,请联系发卡行客服 | | 41 | 不可逆 | 卡片丢失 | 交易不允许,请勿重试 | | 43 | 不可逆 | 卡片被盗 | 交易不允许,请勿重试 | | 46 | 不可逆 | 账户已销户 | 该卡不允许此交易,请勿重试 | | 51 | 可逆 | 余额/额度不足 | 未获授权 | | 54 | 不可逆 | 卡片过期/有效期无效 | 请核对卡片信息 | | 55 | 可逆 | 密码错误 | 密码错误 | | 57 | 不可逆 | 该卡不允许此交易 | 该卡不允许此交易,请勿重试 | | 57 | 不可逆 | 终端能力不支持该交易 | 交易不允许,请勿重试 | | 57 | 不可逆 | 确认欺诈 | 该卡不允许此交易,请勿重试 | | 57 | 不可逆 | 因违反法律交易被拒 | 该卡不允许此交易,请勿重试 | | 58 | 不可逆 | 商户无效 | 交易不允许,请勿重试 | | 59 | 可逆 | 疑似欺诈/出行提醒 | 请联系发卡行客服 | | 61 | 可逆 | 金额超限/取现 | 金额超限,请联系发卡行客服 | | 62 | 可逆 | 临时冻结(如逾期欠款) | 请联系发卡行客服 | | 62 | 不可逆 | 境内卡发起跨境交易 | 该卡不支持跨境交易 | | 63 | 不可逆 | 安全校验失败(无效或缺失) | 请核对卡片信息 | | 64 | 不可逆 | 交易最低金额无效 | 交易金额不允许,请勿重试 | | 65 | 可逆 | 取现次数超限 | 取现次数超限,请联系发卡行客服 | | 75 | 可逆 | 密码尝试次数超限/取现 | 密码尝试次数超限,请联系发卡行客服 | | 76 | 不可逆 | 目标账户无效或不存在 | 目标账户无效,请勿重试 | | 77 | 不可逆 | 来源账户无效或不存在 | 来源账户无效,请勿重试 | | 78 | 可逆 | 新卡未解锁(含客户在 App 中锁卡的情况,电商 NFC) | 请解锁卡片 | | 82 | 不可逆 | 卡片无效(密文) | 卡片错误,请勿重试 | | 83 | 不可逆 | 密码过期/密码加密错误 | 密码错误,请勿重试 | | 91 | 可逆 | 发卡行系统不可用 | 通讯故障,请稍后重试 | | 96 | 可逆 | 系统故障 | 通讯故障,请稍后重试 | | AB | 可逆 | 卡功能选择错误(借记) | 请使用贷记功能 | | AC | 可逆 | 卡功能选择错误(贷记) | 请使用借记功能 | | FM | 不可逆 | 需使用芯片 | 请使用芯片 | | P5 | 不可逆 | 修改密码/解锁 | 密码错误,请勿重试 | | P6 | 可逆 | 新密码未被接受 | 密码错误,请使用新密码 | ## Visa 卡组织 [#visa-卡组织] | ABECS 代码 | 代码类型 | 消息 | POS/电商消息 | | -------- | ---- | ----------------------------- | ----------------- | | 3 | 不可逆 | 商户无效 | 交易不允许,请勿重试 | | 4 | 不可逆 | 没收卡片 | 请联系发卡行客服,请勿重试 | | 5 | 可逆 | 通用拒绝 | 请联系发卡行客服 | | 6 | 不可逆 | 卡片错误 | 请核对卡片信息 | | 7 | 不可逆 | 确认欺诈 | 该卡不允许此交易,请勿重试 | | 12 | 不可逆 | 报文格式错误 | 卡片错误,请勿重试 | | 13 | 不可逆 | 交易金额无效 | 交易金额不允许,请勿重试 | | 14 | 不可逆 | 卡号不属于该发卡行/卡号无效 | 请核对卡片信息 | | 15 | 不可逆 | 未找到发卡行,BIN 错误(收单机构拒绝) | 卡片信息无效,请勿重试 | | 19 | 不可逆 | 收单机构故障 | 卡片错误,请勿重试 | | 39 | 可逆 | 卡功能选择错误(贷记) | 请使用借记功能 | | 41 | 不可逆 | 卡片丢失 | 交易不允许,请勿重试 | | 43 | 不可逆 | 卡片被盗 | 交易不允许,请勿重试 | | 46 | 不可逆 | 账户已销户 | 该卡不允许此交易,请勿重试 | | 51 | 可逆 | 余额/额度不足 | 未获授权 | | 54 | 不可逆 | 卡片过期/有效期无效 | 请核对卡片信息 | | 57 | 不可逆 | 该卡不允许此交易 | 该卡不允许此交易,请勿重试 | | 58 | 不可逆 | 终端能力不支持该交易 | 交易不允许,请勿重试 | | 59 | 可逆 | 疑似欺诈/出行提醒 | 请联系发卡行客服 | | 62 | 可逆 | 临时冻结(如逾期欠款) | 请联系发卡行客服 | | 62 | 可逆 | 境内卡发起跨境交易 | 该卡不支持跨境交易 | | 64 | 不可逆 | 不符合反洗钱法律要求 | 请联系发卡行客服,请勿重试 | | 65 | 可逆 | 取现次数超限 | 取现次数超限,请联系发卡行客服 | | 75 | 可逆 | 密码尝试次数超限/消费 | 密码尝试次数超限,请联系发卡行客服 | | 75 | 可逆 | 密码尝试次数超限/取现 | 密码尝试次数超限,请联系发卡行客服 | | 76 | 不可逆 | 冲正无效 | 请联系发卡行客服,请勿重试 | | 78 | 可逆 | 新卡未解锁(含客户在 App 中锁卡的情况,电商 NFC) | 请解锁卡片 | | 82 | 不可逆 | 卡片无效(密文) | 卡片错误,请勿重试 | | 91 | 可逆 | 发卡行系统不可用 | 通讯故障,请稍后重试 | | 92 | 不可逆 | 路由未找到 | 请联系发卡行客服,请勿重试 | | 93 | 不可逆 | 因违反法律交易被拒 | 该卡不允许此交易,请勿重试 | | 94 | 不可逆 | 追踪数据值重复 | 请联系发卡行客服,请勿重试 | | 96 | 可逆 | 系统故障 | 通讯故障,请稍后重试 | | 52 或 53 | 可逆 | 卡功能选择错误(借记) | 请使用贷记功能 | | 55 或 86 | 可逆 | 密码错误 | 密码错误 | | 61 或 N4 | 可逆 | 金额超限/取现 | 金额超限,请联系发卡行客服 | | 6P | 不可逆 | ID 校验失败 | ID 验证失败 | | 74 或 81 | 不可逆 | 密码过期/密码加密错误 | 密码错误,请勿重试 | | B1 | 可逆 | 不支持附加费(surcharge) | 请联系发卡行客服 | | B2 | 可逆 | 借记网络不支持附加费(surcharge) | 请联系发卡行客服 | | N0 | 可逆 | 强制 STIP | 请联系发卡行客服 | | N3 | 不可逆 | 取现不可用 | 取现不可用,请勿重试 | | N7 | 不可逆 | 安全校验失败(无效或缺失) | 请核对卡片信息 | | N7 | 不可逆 | 动态密钥变更错误 | 卡片错误,请勿重试 | | N8 | 不可逆 | 与预授权金额不符 | 金额与预授权不一致,请勿重试 | | R0 | 不可逆 | 针对某一服务的循环扣款已暂停 | 该服务的循环扣款已暂停,请勿重试 | | R1 | 不可逆 | 针对所有服务的循环扣款已暂停 | 该服务的循环扣款已暂停,请勿重试 | | R2 | 不可逆 | 交易不符合 Visa PIN 要求 | 该卡不允许此交易,请勿重试 | | R3 | 不可逆 | 所有授权指令已暂停 | 该服务的循环扣款已暂停,请勿重试 | Visa 新增重试代码:5C 和 9G。5C 和 9G 是 Visa 卡组织新增的拒绝代码。有关这些代码的完整重试规则,请查阅[卡组织重试计划](/docs/cartao/retry-program)。 ## Mastercard/Hiper 卡组织 [#mastercardhiper-卡组织] | ABECS 代码 | 代码类型 | 消息 | POS/电商消息 | | -------- | ---- | ----------------------------- | ----------------- | | 3 | 不可逆 | 商户无效 | 交易不允许,请勿重试 | | 4 | 不可逆 | 没收卡片 | 请联系发卡行客服,请勿重试 | | 4 | 不可逆 | 确认欺诈 | 该卡不允许此交易,请勿重试 | | 5 | 可逆 | 通用拒绝 | 请联系发卡行客服 | | 12 | 不可逆 | 分期金额无效 | 分期方案无效,请勿重试 | | 13 | 不可逆 | 交易金额无效 | 交易金额不允许,请勿重试 | | 13 | 不可逆 | 交易最低金额无效 | 交易金额不允许,请勿重试 | | 14 或 1 | 不可逆 | 卡号不属于该发卡行/卡号无效 | 请核对卡片信息 | | 15 | 不可逆 | 未找到发卡行,BIN 错误(收单机构拒绝) | 卡片信息无效,请勿重试 | | 30 | 不可逆 | 收单机构故障 | 卡片错误,请勿重试 | | 30 | 不可逆 | 报文格式错误 | 卡片错误,请勿重试 | | 41 | 不可逆 | 卡片丢失 | 交易不允许,请勿重试 | | 43 | 不可逆 | 卡片被盗 | 交易不允许,请勿重试 | | 51 | 可逆 | 余额/额度不足 | 未获授权 | | 54 | 不可逆 | 卡片过期/有效期无效 | 请核对卡片信息 | | 55 | 可逆 | 密码错误 | 密码错误 | | 55 | 可逆 | 新密码未被接受 | 密码错误,请使用新密码 | | 57 | 可逆 | 该卡不允许此交易 | 该卡不允许此交易 | | 57 | 可逆 | 临时冻结(如逾期欠款) | 请联系发卡行客服 | | 57 | 可逆 | 新卡未解锁(含客户在 App 中锁卡的情况,电商 NFC) | 请解锁卡片 | | 58 | 不可逆 | 终端能力不支持该交易 | 交易不允许,请勿重试 | | 61 | 可逆 | 金额超限/取现 | 金额超限,请联系发卡行客服 | | 62 | 不可逆 | 境内卡发起跨境交易 | 该卡不支持跨境交易 | | 62 | 不可逆 | 因违反法律交易被拒 | 该卡不允许此交易,请勿重试 | | 62 | 不可逆 | 账户已销户 | 该卡不允许此交易,请勿重试 | | 63 | 可逆 | 安全校验失败(无效或缺失) | 请核对卡片信息 | | 63 | 可逆 | 疑似欺诈/出行提醒 | 请联系发卡行客服 | | 65 | 可逆 | 取现次数超限 | 取现次数超限,请联系发卡行客服 | | 75 | 可逆 | 密码尝试次数超限/取现 | 密码尝试次数超限,请联系发卡行客服 | | 88 | 不可逆 | 密码过期/密码加密错误 | 密码错误,请勿重试 | | 88 | 不可逆 | 卡片无效(密文) | 卡片错误,请勿重试 | | 91 | 可逆 | 发卡行系统不可用 | 通讯故障,请稍后重试 | | 92 | 不可逆 | 路由未找到 | 请联系发卡行客服,请勿重试 | | 94 | 不可逆 | 追踪数据值重复 | 请联系发卡行客服,请勿重试 | | 96 | 可逆 | 系统故障 | 通讯故障,请稍后重试 | ## Amex 卡组织 [#amex-卡组织] | ABECS 代码 | AMEX 与 PayZu 对照 | 代码类型 | 消息 | POS/电商消息 | | :------- | :-------------- | :--- | :------------- | :---------------- | | 100 | FA | 可逆 | 通用拒绝 | 请联系发卡行客服 | | 100 | FA | 可逆 | 疑似欺诈/出行提醒 | 请联系发卡行客服 | | 101 | BV | 不可逆 | 卡片过期/有效期无效 | 请核对卡片信息 | | 106 | A4 | 可逆 | 密码尝试次数超限/消费 | 密码尝试次数超限,请联系发卡行客服 | | 106 | A4 | 可逆 | 密码尝试次数超限/取现 | 密码尝试次数超限,请联系发卡行客服 | | 109 | DA | 不可逆 | 商户无效 | 交易不允许,请勿重试 | | 110 | JB | 不可逆 | 交易金额无效 | 交易金额不允许,请勿重试 | | 115 | A2 | 不可逆 | 卡片错误 | 请核对卡片信息 | | 115 | A2 | 不可逆 | 分期金额无效 | 分期方案无效,请勿重试 | | 116 | A5 | 可逆 | 余额/额度不足 | 未获授权 | | 117 | A6 | 可逆 | 密码错误 | 密码错误 | | 121 | A5 | 可逆 | 余额/额度不足 | 未获授权 | | 122 | 8 | 不可逆 | 卡号不属于该发卡行/卡号无效 | 请核对卡片信息 | | 122 | 8 | 不可逆 | 安全校验失败(无效或缺失) | 请核对卡片信息 | | 180 | A7 | 不可逆 | 密码过期/密码加密错误 | 密码错误,请勿重试 | | 180 | A7 | 不可逆 | 卡片无效(密文) | 卡片错误,请勿重试 | | 181 | A3 | 不可逆 | 报文格式错误 | 卡片错误,请勿重试 | | 200 | N/A | 不可逆 | 该卡不允许此交易 | 该卡不允许此交易,请勿重试 | | 200 | FD | 不可逆 | 卡片丢失 | 交易不允许,请勿重试 | | 200 | FD | 不可逆 | 卡片被盗 | 交易不允许,请勿重试 | | 200 | FD | 不可逆 | 确认欺诈 | 该卡不允许此交易,请勿重试 | | 911 | AE | 可逆 | 系统故障 | 通讯故障,请稍后重试 | | 912 | A1 | 可逆 | 发卡行系统不可用 | 通讯故障,请稍后重试 | # Activity branches (/docs/cartao/activity-branches.en) Every merchant is classified by an activity branch that describes its line of business. Use the table below to find the matching code. # Ramos de atividade (/docs/cartao/activity-branches) Cada estabelecimento é classificado por um ramo de atividade, que descreve o tipo de negócio. Use a tabela abaixo para encontrar o código do ramo correspondente. # 经营类别 (/docs/cartao/activity-branches.zh) 每个商户都按经营类别分类，用于描述其经营类型。用下表查找对应的代码。 # Antifraud (/docs/cartao/antifraud.en) Charges sent with the `fraudAnalysis` object go through **Cybersource** fraud screening in real time before authorization. You control per charge whether the analysis runs and what to do with the result. The antifraud analysis can: * **Approve** the transaction automatically * **Reject** the transaction on suspicion of fraud * **Route it to manual review**, according to previously defined rules Sending `fraudAnalysis` is **required** for international charges. See [International charge](/docs/cartao/international). ## How it works [#how-it-works] When a charge is created with the `fraudAnalysis` object, the operation is submitted to a risk assessment based on several criteria, such as customer data, purchase behavior, and order characteristics. To use the antifraud, simply include the `fraudAnalysis` object inside `creditCardPayment` in the transaction creation request. This object carries the device identifier (`fingerPrintId`), the browser data (`browser`) and the MDD fields (`definedFields`). ```json { "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` For the list of values that can be passed in `definedFields`, see the [MDD table](/docs/cartao/mdds). The transaction response can contain the following antifraud statuses: | Status | Description | | ------------- | ------------------------------------------ | | `Approved` | Transaction approved after risk analysis | | `Rejected` | Transaction rejected on suspicion of fraud | | `UnderReview` | Transaction under manual review | ## Capturing the fingerPrintId [#capturing-the-fingerprintid] The `fingerPrintId` is a random session id generated by the client itself, which must be used in the payment request. Each fingerprint is unique and valid for 48 hours. ### Load the script [#load-the-script] To obtain a fingerprint, you will need to load the following script in your HTML page: ```html ``` ### Generate the id and activate the fingerprint [#generate-the-id-and-activate-the-fingerprint] After that, you must generate a random id that will be your fingerprint and use our script to activate it. Complete example: ```html ``` Parameters of the `init` function: | Parameter | Default value | Required? | | ------------ | ------------- | --------- | | `identifier` | \* | Yes | | `sandbox` | false | No | After activating it, you can already use your fingerprint inside the `fraudAnalysis` field to create a payment request. ### Send fraudAnalysis in the charge [#send-fraudanalysis-in-the-charge] To create a charge using the antifraud, you must provide the `fraudAnalysis` field inside `creditCardPayment`. Inside `browser`, the `cookiesAccepted` and `ipAddress` fields are required. ```json { "customer": { "name": "João Silva", "identity": "12345678900", "identityType": "CPF", "email": "joao.silva@example.com", "phone": "5511912345678", "address": { "street": "Rua das Flores", "number": "123", "zipCode": "01234567", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Centro" } }, "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` When creating a charge using the antifraud, all `customer` fields except `complement` and `birthdate` become required. ## Next steps [#next-steps] # Antifraude (/docs/cartao/antifraud) Cobranças enviadas com o objeto `fraudAnalysis` passam em tempo real pelo antifraude **Cybersource** antes da autorização. Você controla por cobrança se a análise roda e o que fazer com o resultado. A análise antifraude pode: * **Aprovar** automaticamente a transação * **Recusar** a transação por suspeita de fraude * **Encaminhar para análise manual**, de acordo com regras previamente definidas O envio de `fraudAnalysis` é **obrigatório** em cobranças internacionais. Consulte [Cobrança internacional](/docs/cartao/international). ## Como funciona [#como-funciona] Quando a cobrança é criada com o objeto `fraudAnalysis`, a operação é submetida a uma avaliação de risco com base em diversos critérios, como dados do cliente, comportamento de compra e características do pedido. Para utilizar o antifraude, basta incluir o objeto `fraudAnalysis` dentro de `creditCardPayment` na requisição de criação da transação. Esse objeto leva o identificador do dispositivo (`fingerPrintId`), os dados do navegador (`browser`) e os campos MDD (`definedFields`). ```json { "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` Para uma lista de valores que podem ser passados em `definedFields`, consulte a [Tabela de MDDs](/docs/cartao/mdds). A resposta da transação pode conter os seguintes status de antifraude: | Status | Descrição | | ------------- | ----------------------------------------- | | `Approved` | Transação aprovada após análise de risco | | `Rejected` | Transação recusada por suspeita de fraude | | `UnderReview` | Transação em análise manual | ## Captura do fingerPrintId [#captura-do-fingerprintid] O `fingerPrintId` é um id de sessão aleatório gerado pelo próprio cliente, que deve ser utilizado para a requisição de pagamento. Cada fingerprint é único e válido por 48 horas. ### Carregar o script [#carregar-o-script] Para obter um fingerprint, você precisará carregar o seguinte script em sua página HTML: ```html ``` ### Gerar o id e ativar o fingerprint [#gerar-o-id-e-ativar-o-fingerprint] Após isso, você deverá gerar um id aleatório que será o seu fingerprint e utilizar o nosso script para ativá-lo. Exemplo completo: ```html ``` Parâmetros da função `init`: | Parâmetro | Valor Padrão | Obrigatório? | | ------------ | ------------ | ------------ | | `identifier` | \* | Sim | | `sandbox` | false | Não | Após ativá-lo, você já pode usar seu fingerprint dentro do campo `fraudAnalysis` para criar uma requisição de pagamento. ### Enviar fraudAnalysis na cobrança [#enviar-fraudanalysis-na-cobrança] Para criar uma cobrança utilizando o antifraude, é necessário informar o campo `fraudAnalysis` dentro de `creditCardPayment`. Dentro de `browser`, os campos `cookiesAccepted` e `ipAddress` são obrigatórios. ```json { "customer": { "name": "João Silva", "identity": "12345678900", "identityType": "CPF", "email": "joao.silva@example.com", "phone": "5511912345678", "address": { "street": "Rua das Flores", "number": "123", "zipCode": "01234567", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Centro" } }, "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` Ao realizar cobrança utilizando o antifraude, todos os campos de `customer`, exceto `complement` e `birthdate`, se tornam obrigatórios. ## Próximos passos [#próximos-passos] # 反欺诈 (/docs/cartao/antifraud.zh) 携带 `fraudAnalysis` 对象的收款会在授权前实时经过 **Cybersource** 反欺诈筛查。您可以按收款控制是否执行分析，以及如何处理分析结果。 反欺诈分析可以: * 自动**批准**交易 * 因涉嫌欺诈而**拒绝**交易 * 根据预先定义的规则**转入人工审核** 在跨境收款中,`fraudAnalysis` 为**必填**。请参阅[跨境收款](/docs/cartao/international)。 ## 工作原理 [#工作原理] 当收款携带 `fraudAnalysis` 对象创建时，该操作会进入风险评估，评估基于多种标准，例如客户数据、购买行为和订单特征。 要使用反欺诈,只需在创建交易请求的 `creditCardPayment` 内包含 `fraudAnalysis` 对象。该对象携带设备标识(`fingerPrintId`)、浏览器数据(`browser`)和 MDD 字段(`definedFields`)。 ```json { "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` `definedFields` 中可传入的取值列表请参阅 [MDD 字段表](/docs/cartao/mdds)。 交易响应中可能包含以下反欺诈状态: | 状态 | 描述 | | ------------- | ----------- | | `Approved` | 交易经风险分析后被批准 | | `Rejected` | 交易因涉嫌欺诈被拒绝 | | `UnderReview` | 交易处于人工审核中 | ## 获取 fingerPrintId [#获取-fingerprintid] `fingerPrintId` 是由客户端自行生成的随机会话 id,应在支付请求中使用。每个 fingerprint 都是唯一的,有效期为 48 小时。 ### 加载脚本 [#加载脚本] 要获取 fingerprint,您需要在 HTML 页面中加载以下脚本: ```html ``` ### 生成 id 并激活 fingerprint [#生成-id-并激活-fingerprint] 之后,您需要生成一个随机 id 作为您的 fingerprint,并使用我们的脚本激活它。 完整示例: ```html ``` `init` 函数的参数: | 参数 | 默认值 | 是否必填 | | ------------ | ----- | ---- | | `identifier` | \* | 是 | | `sandbox` | false | 否 | 激活后,即可在 `fraudAnalysis` 字段中使用您的 fingerprint 来创建支付请求。 ### 在收款中发送 fraudAnalysis [#在收款中发送-fraudanalysis] 要使用反欺诈创建收款,需要在 `creditCardPayment` 中提供 `fraudAnalysis` 字段。在 `browser` 中,`cookiesAccepted` 和 `ipAddress` 字段为必填。 ```json { "customer": { "name": "João Silva", "identity": "12345678900", "identityType": "CPF", "email": "joao.silva@example.com", "phone": "5511912345678", "address": { "street": "Rua das Flores", "number": "123", "zipCode": "01234567", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Centro" } }, "creditCardPayment": { "fraudAnalysis": { "fingerPrintId": "xyz123fingerprint", "browser": { "cookiesAccepted": true, "email": "joao.silva@example.com", "hostName": "host.example.com", "ipAddress": "192.168.0.1", "type": "Chrome" }, "definedFields": [ { "id": 1, "value": "Guest" } ] } } } ``` 使用反欺诈进行收款时,`customer` 的所有字段(`complement` 和 `birthdate` 除外)均变为必填。 ## 后续步骤 [#后续步骤] # Authentication (/docs/cartao/authentication.en) Authentication in the **Card API** happens in two layers that work together: 1. **Mutual TLS (mTLS)**: every connection to the API uses a client certificate issued by PayZu, guaranteeing the identity of both the server and the client during communication. 2. **JWT token**: over the mTLS connection, you obtain an `access_token` via [`POST /token`](/docs/cartao/endpoints/token/post_token) and send it in the `Authorization: Bearer` header on all other routes. ## Environments [#environments] | Environment | Base URL | | ----------- | --------------------------------- | | Production | `https://api.payzu.io/v1` | | Sandbox | `https://api.sandbox.payzu.io/v1` | ## Mutual TLS [#mutual-tls] Before making any call, install the client certificate provided by the PayZu team and configure your system to use it in **all** API calls, always over HTTPS. In `curl`, the certificate goes in through the `--cert` (client certificate), `--key` (private key), and `--cacert` (certificate authority chain) flags: ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` ## Get the token [#get-the-token] The [`POST /token`](/docs/cartao/endpoints/token/post_token) route returns a JWT token used to authenticate the other routes. It uses **Basic Auth** (your `client_id` as the username and `client_secret` as the password), always over the mTLS connection, and receives the `grant_type` `client_credentials` in the body: ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/token \ --user "$CLIENT_ID:$CLIENT_SECRET" \ --header 'content-type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "grant_type": "client_credentials" }' ``` In production, switch the base URL to `https://api.payzu.io/v1`. The response carries the token and its expiration time: ```json { "access_token": "string", "token_type": "string", "expires_in": 0 } ``` | Field | What it's for | | -------------- | ---------------------------------------------------------------- | | `access_token` | JWT token used in the `Authorization` header of the other routes | | `token_type` | Type of the returned token | | `expires_in` | Token validity period, in seconds | ## Authenticated calls [#authenticated-calls] After obtaining the token, every API route receives the `Authorization: Bearer` header, always over the same mTLS configuration: ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` Never expose the `client_secret` or the client certificate's private key. Do not send them to the front-end, do not commit them to a repository, and keep them in a secrets vault. If you suspect they have been compromised, contact the PayZu team for a replacement. ## Next steps [#next-steps] # Autenticação (/docs/cartao/authentication) A autenticação da **API Cartão** acontece em duas camadas que trabalham juntas: 1. **Mutual TLS (mTLS)**: toda conexão com a API usa um certificado de cliente emitido pela PayZu, garantindo a identidade tanto do servidor quanto do cliente durante a comunicação. 2. **Token JWT**: sobre a conexão mTLS, você obtém um `access_token` via [`POST /token`](/docs/cartao/endpoints/token/post_token) e o envia no header `Authorization: Bearer` em todas as demais rotas. ## Ambientes [#ambientes] | Ambiente | URL base | | -------- | --------------------------------- | | Produção | `https://api.payzu.io/v1` | | Sandbox | `https://api.sandbox.payzu.io/v1` | ## Mutual TLS [#mutual-tls] Antes de qualquer chamada, instale o certificado de cliente fornecido pela equipe PayZu e configure seu sistema para utilizá-lo em **todas** as chamadas à API, sempre por HTTPS. No `curl`, o certificado entra pelas flags `--cert` (certificado do cliente), `--key` (chave privada) e `--cacert` (cadeia da autoridade certificadora): ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` ## Obter o token [#obter-o-token] A rota [`POST /token`](/docs/cartao/endpoints/token/post_token) retorna um token JWT para autenticação das rotas. Ela usa **Basic Auth** (seu `client_id` como usuário e `client_secret` como senha), sempre sobre a conexão mTLS, e recebe o `grant_type` `client_credentials` no corpo: ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/token \ --user "$CLIENT_ID:$CLIENT_SECRET" \ --header 'content-type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "grant_type": "client_credentials" }' ``` Em produção, troque a base URL para `https://api.payzu.io/v1`. A resposta traz o token e o tempo de expiração: ```json { "access_token": "string", "token_type": "string", "expires_in": 0 } ``` | Campo | Para que serve | | -------------- | ---------------------------------------------------------- | | `access_token` | Token JWT usado no header `Authorization` das demais rotas | | `token_type` | Tipo do token retornado | | `expires_in` | Tempo de validade do token, em segundos | ## Chamadas autenticadas [#chamadas-autenticadas] Depois de obter o token, toda rota da API recebe o header `Authorization: Bearer`, sempre sobre a mesma configuração de mTLS: ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` Nunca exponha o `client_secret` nem a chave privada do certificado de cliente. Não os envie ao front-end, não os suba em repositório e guarde-os em um cofre de segredos. Se houver suspeita de comprometimento, entre em contato com a equipe PayZu para substituição. ## Próximos passos [#próximos-passos] # 身份认证 (/docs/cartao/authentication.zh) **信用卡 API** 的认证由两层机制协同完成: 1. **双向 TLS(mTLS)**:与 API 的每个连接都使用由 PayZu 签发的客户端证书,在通信过程中同时保证服务器和客户端的身份。 2. **JWT token**:在 mTLS 连接之上,通过 [`POST /token`](/docs/cartao/endpoints/token/post_token) 获取 `access_token`,并在所有其他路由的 `Authorization: Bearer` header 中发送。 ## 环境 [#环境] | 环境 | 基础 URL | | ------- | --------------------------------- | | 生产环境 | `https://api.payzu.io/v1` | | Sandbox | `https://api.sandbox.payzu.io/v1` | ## Mutual TLS [#mutual-tls] 在发起任何调用之前,请安装 PayZu 团队提供的客户端证书,并将您的系统配置为在对 API 的**所有**调用中使用该证书,且始终通过 HTTPS。 在 `curl` 中,证书通过 `--cert`(客户端证书)、`--key`(私钥)和 `--cacert`(证书颁发机构链)这几个标志传入: ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` ## 获取 token [#获取-token] [`POST /token`](/docs/cartao/endpoints/token/post_token) 路由返回用于各路由认证的 JWT token。它使用 **Basic Auth**(`client_id` 作为用户名,`client_secret` 作为密码),始终在 mTLS 连接之上,并在请求体中接收值为 `client_credentials` 的 `grant_type`: ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/token \ --user "$CLIENT_ID:$CLIENT_SECRET" \ --header 'content-type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "grant_type": "client_credentials" }' ``` 在生产环境中,请将基础 URL 换成 `https://api.payzu.io/v1`。 响应包含 token 及其过期时间: ```json { "access_token": "string", "token_type": "string", "expires_in": 0 } ``` | 字段 | 用途 | | -------------- | -------------------------------------------- | | `access_token` | 在其他路由的 `Authorization` header 中使用的 JWT token | | `token_type` | 返回的 token 类型 | | `expires_in` | token 的有效期,以秒为单位 | ## 认证调用 [#认证调用] 获取 token 之后,API 的每个路由都在同样的 mTLS 配置之上接收 `Authorization: Bearer` header: ```bash curl --request GET \ --url https://api.sandbox.payzu.io/v1/charges \ --header 'accept: application/json' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` 切勿泄露 `client_secret` 或客户端证书的私钥。不要将它们发送到前端,不要提交到代码仓库,并请保存在密钥保管库中。如怀疑发生泄露,请联系 PayZu 团队进行更换。 ## 后续步骤 [#后续步骤] # Bank compensation codes (/docs/cartao/compensation-codes.en) Every bank in the Brazilian financial system has a three-digit compensation code that identifies it. Use the table below to find a bank's code. # Códigos de compensação (/docs/cartao/compensation-codes) Cada banco do sistema financeiro brasileiro tem um código de compensação de três dígitos que o identifica. Use a tabela abaixo para encontrar o código de um banco. # 银行清算代码 (/docs/cartao/compensation-codes.zh) 巴西金融系统中的每家银行都有一个三位数的清算代码用于标识。用下表查找某家银行的代码。 # Supported currencies (/docs/cartao/currencies.en) Currency codes accepted by the API, in ISO 4217. Send the three-letter code in the request's currency field. This list reflects the set accepted by the API (157 currencies). | Currency | Code | | ---------------------------- | ----- | | UAE Dirham | `AED` | | Afghan Afghani | `AFN` | | Albanian Lek | `ALL` | | Armenian Dram | `AMD` | | Angolan Kwanza | `AOA` | | Argentine Peso | `ARS` | | Australian Dollar | `AUD` | | Aruban Florin | `AWG` | | Barbadian Dollar | `BBD` | | Bangladeshi Taka | `BDT` | | Bulgarian Lev | `BGN` | | Bahraini Dinar | `BHD` | | Burundian Franc | `BIF` | | Bermudian Dollar | `BMD` | | Brunei Dollar | `BND` | | Bolivian Boliviano | `BOB` | | Brazilian Real | `BRL` | | Bahamian Dollar | `BSD` | | Bhutanese Ngultrum | `BTN` | | Botswana Pula | `BWP` | | Belarusian Ruble | `BYN` | | Belize Dollar | `BZD` | | Canadian Dollar | `CAD` | | Congolese Franc | `CDF` | | Swiss Franc | `CHF` | | Chilean Unit of Account (UF) | `CLF` | | Chilean Peso | `CLP` | | Chinese Yuan (offshore) | `CNH` | | Chinese Yuan | `CNY` | | Colombian Peso | `COP` | | Colombian Real Value Unit | `COU` | | Costa Rican Colón | `CRC` | | Cuban Peso | `CUP` | | Cape Verdean Escudo | `CVE` | | Czech Koruna | `CZK` | | Djiboutian Franc | `DJF` | | Danish Krone | `DKK` | | Dominican Peso | `DOP` | | Algerian Dinar | `DZD` | | Egyptian Pound | `EGP` | | Eritrean Nakfa | `ERN` | | Ethiopian Birr | `ETB` | | Euro | `EUR` | | Fijian Dollar | `FJD` | | Falkland Islands Pound | `FKP` | | Pound Sterling | `GBP` | | Georgian Lari | `GEL` | | Ghanaian Cedi | `GHS` | | Gibraltar Pound | `GIP` | | Gambian Dalasi | `GMD` | | Guinean Franc | `GNF` | | Guatemalan Quetzal | `GTQ` | | Guyanese Dollar | `GYD` | | Hong Kong Dollar | `HKD` | | Honduran Lempira | `HNL` | | Haitian Gourde | `HTG` | | Hungarian Forint | `HUF` | | Indonesian Rupiah | `IDR` | | Israeli New Shekel | `ILS` | | Indian Rupee | `INR` | | Iraqi Dinar | `IQD` | | Iranian Rial | `IRR` | | Icelandic Króna | `ISK` | | Jamaican Dollar | `JMD` | | Jordanian Dinar | `JOD` | | Japanese Yen | `JPY` | | Kenyan Shilling | `KES` | | Kyrgyzstani Som | `KGS` | | Cambodian Riel | `KHR` | | Comorian Franc | `KMF` | | South Korean Won | `KRW` | | Kuwaiti Dinar | `KWD` | | Cayman Islands Dollar | `KYD` | | Kazakhstani Tenge | `KZT` | | Lao Kip | `LAK` | | Lebanese Pound | `LBP` | | Sri Lankan Rupee | `LKR` | | Liberian Dollar | `LRD` | | Lesotho Loti | `LSL` | | Libyan Dinar | `LYD` | | Moroccan Dirham | `MAD` | | Moldovan Leu | `MDL` | | Malagasy Ariary | `MGA` | | Macedonian Denar | `MKD` | | Myanmar Kyat | `MMK` | | Mongolian Tögrög | `MNT` | | Macanese Pataca | `MOP` | | Mauritanian Ouguiya (old) | `MRO` | | Mauritanian Ouguiya | `MRU` | | Mauritian Rupee | `MUR` | | Maldivian Rufiyaa | `MVR` | | Malawian Kwacha | `MWK` | | Mexican Peso | `MXN` | | Malaysian Ringgit | `MYR` | | Mozambican Metical | `MZN` | | Namibian Dollar | `NAD` | | Nigerian Naira | `NGN` | | Nicaraguan Córdoba | `NIO` | | Norwegian Krone | `NOK` | | Nepalese Rupee | `NPR` | | New Zealand Dollar | `NZD` | | Omani Rial | `OMR` | | Panamanian Balboa | `PAB` | | Peruvian Sol | `PEN` | | Papua New Guinean Kina | `PGK` | | Philippine Peso | `PHP` | | Pakistani Rupee | `PKR` | | Polish Złoty | `PLN` | | Paraguayan Guaraní | `PYG` | | Qatari Riyal | `QAR` | | Romanian Leu | `RON` | | Serbian Dinar | `RSD` | | Russian Ruble | `RUB` | | Rwandan Franc | `RWF` | | Saudi Riyal | `SAR` | | Solomon Islands Dollar | `SBD` | | Seychellois Rupee | `SCR` | | Sudanese Pound | `SDG` | | Special Drawing Rights | `SDR` | | Swedish Krona | `SEK` | | Singapore Dollar | `SGD` | | Saint Helena Pound | `SHP` | | Sierra Leonean Leone | `SLL` | | Somali Shilling | `SOS` | | Surinamese Dollar | `SRD` | | South Sudanese Pound | `SSP` | | São Tomé and Príncipe Dobra | `STN` | | Salvadoran Colón | `SVC` | | Syrian Pound | `SYP` | | Swazi Lilangeni | `SZL` | | Thai Baht | `THB` | | Tajikistani Somoni | `TJS` | | Turkmenistani Manat | `TMT` | | Tunisian Dinar | `TND` | | Tongan Paʻanga | `TOP` | | Turkish Lira | `TRY` | | Trinidad and Tobago Dollar | `TTD` | | New Taiwan Dollar | `TWD` | | Tanzanian Shilling | `TZS` | | Ukrainian Hryvnia | `UAH` | | Ugandan Shilling | `UGX` | | US Dollar | `USD` | | Uruguayan Peso | `UYU` | | Uzbekistani Som | `UZS` | | Venezuelan Bolívar | `VES` | | Vietnamese Dong | `VND` | | Vanuatu Vatu | `VUV` | | Samoan Tala | `WST` | | Central African CFA Franc | `XAF` | | Gold (troy ounce) | `XAU` | | East Caribbean Dollar | `XCD` | | Caribbean Guilder | `XCG` | | West African CFA Franc | `XOF` | | CFP Franc | `XPF` | | Yemeni Rial | `YER` | | South African Rand | `ZAR` | | Zambian Kwacha | `ZMW` | # Moedas suportadas (/docs/cartao/currencies) Códigos de moeda aceitos pela API, no padrão ISO 4217. Envie o código de três letras no campo de moeda da requisição. Esta lista reflete o conjunto aceito pela API (157 moedas). | Moeda | Código | | -------------------------------- | ------ | | Dirham dos Emirados | `AED` | | Afghani do Afeganistão | `AFN` | | Lek Albanês | `ALL` | | Dram Armênio | `AMD` | | Kwanza Angolano | `AOA` | | Peso Argentino | `ARS` | | Dólar Australiano | `AUD` | | Florim Arubano | `AWG` | | Dólar de Barbados | `BBD` | | Taka de Bangladesh | `BDT` | | Lev Búlgaro | `BGN` | | Dinar do Bahrein | `BHD` | | Franco Burundês | `BIF` | | Dólar das Bermudas | `BMD` | | Dólar de Brunei | `BND` | | Boliviano | `BOB` | | Real Brasileiro | `BRL` | | Dólar das Bahamas | `BSD` | | Ngultrum Butanês | `BTN` | | Pula de Botswana | `BWP` | | Rublo Bielorrusso | `BYN` | | Dólar de Belize | `BZD` | | Dólar Canadense | `CAD` | | Franco Congolês | `CDF` | | Franco Suíço | `CHF` | | Unidade de Fomento Chilena | `CLF` | | Peso Chileno | `CLP` | | Yuan Chinês (offshore) | `CNH` | | Yuan Chinês | `CNY` | | Peso Colombiano | `COP` | | Unidade de Valor Real Colombiana | `COU` | | Colón Costarriquenho | `CRC` | | Peso Cubano | `CUP` | | Escudo cabo-verdiano | `CVE` | | Coroa Checa | `CZK` | | Franco do Djibouti | `DJF` | | Coroa Dinamarquesa | `DKK` | | Peso Dominicano | `DOP` | | Dinar Argelino | `DZD` | | Libra Egípcia | `EGP` | | Nakfa da Eritreia | `ERN` | | Birr Etíope | `ETB` | | Euro | `EUR` | | Dólar de Fiji | `FJD` | | Libra das Malvinas | `FKP` | | Libra Esterlina | `GBP` | | Lari Georgiano | `GEL` | | Cedi Ganês | `GHS` | | Libra de Gibraltar | `GIP` | | Dalasi Gambiano | `GMD` | | Franco Guineense | `GNF` | | Quetzal Guatemalteco | `GTQ` | | Dólar da Guiana | `GYD` | | Dólar de Hong Kong | `HKD` | | Lempira Hondurenha | `HNL` | | Gourde Haitiano | `HTG` | | Florim Húngaro | `HUF` | | Rupia Indonésia | `IDR` | | Novo Shekel Israelense | `ILS` | | Rúpia Indiana | `INR` | | Dinar Iraquiano | `IQD` | | Rial Iraniano | `IRR` | | Coroa Islandesa | `ISK` | | Dólar Jamaicano | `JMD` | | Dinar Jordaniano | `JOD` | | Iene Japonês | `JPY` | | Shilling Queniano | `KES` | | Som Quirguistanês | `KGS` | | Riel Cambojano | `KHR` | | Franco Comorense | `KMF` | | Won Sul-Coreano | `KRW` | | Dinar Kuwaitiano | `KWD` | | Dólar das Ilhas Cayman | `KYD` | | Tengue Cazaquistanês | `KZT` | | Kip Laosiano | `LAK` | | Libra Libanesa | `LBP` | | Rúpia do Sri Lanka | `LKR` | | Dólar Liberiano | `LRD` | | Loti do Lesoto | `LSL` | | Dinar Líbio | `LYD` | | Dirham Marroquino | `MAD` | | Leu Moldávio | `MDL` | | Ariary Madagascarense | `MGA` | | Denar Macedônio | `MKD` | | Kyat de Mianmar | `MMK` | | Tugrik Mongol | `MNT` | | Pataca de Macau | `MOP` | | Ouguiya da Mauritânia (antigo) | `MRO` | | Ouguiya da Mauritânia | `MRU` | | Rupia Mauriciana | `MUR` | | Rufiyaa Maldiva | `MVR` | | Kwacha do Malawi | `MWK` | | Peso Mexicano | `MXN` | | Ringgit Malaio | `MYR` | | Metical de Moçambique | `MZN` | | Dólar Namíbio | `NAD` | | Naira Nigeriana | `NGN` | | Córdoba Nicaraguense | `NIO` | | Coroa Norueguesa | `NOK` | | Rúpia Nepalesa | `NPR` | | Dólar Neozelandês | `NZD` | | Rial Omanense | `OMR` | | Balboa Panamenho | `PAB` | | Sol do Peru | `PEN` | | Kina Papua-Nova Guiné | `PGK` | | Peso Filipino | `PHP` | | Rúpia Paquistanesa | `PKR` | | Zlóti Polonês | `PLN` | | Guarani Paraguaio | `PYG` | | Rial do Catar | `QAR` | | Leu Romeno | `RON` | | Dinar Sérvio | `RSD` | | Rublo Russo | `RUB` | | Franco Ruandês | `RWF` | | Rial Saudita | `SAR` | | Dólar das Ilhas Salomão | `SBD` | | Rupia das Seychelles | `SCR` | | Libra Sudanesa | `SDG` | | Direitos Especiais de Saque | `SDR` | | Coroa Sueca | `SEK` | | Dólar de Singapura | `SGD` | | Libra de Santa Helena | `SHP` | | Leone de Serra Leoa | `SLL` | | Shilling Somali | `SOS` | | Dólar do Suriname | `SRD` | | Libra Sul-Sudanesa | `SSP` | | Dobra de São Tomé e Príncipe | `STN` | | Colón Salvadorenho | `SVC` | | Libra Síria | `SYP` | | Lilangeni da Suazilândia | `SZL` | | Baht Tailandês | `THB` | | Somoni do Tajiquistão | `TJS` | | Manat Turcomeno | `TMT` | | Dinar Tunisiano | `TND` | | Paʻanga de Tonga | `TOP` | | Nova Lira Turca | `TRY` | | Dólar de Trinidad e Tobago | `TTD` | | Dólar Taiuanês | `TWD` | | Shilling Tanzaniano | `TZS` | | Hryvinia Ucraniana | `UAH` | | Shilling Ugandense | `UGX` | | Dólar Americano | `USD` | | Peso Uruguaio | `UYU` | | Som Uzbeque | `UZS` | | Bolívar Venezuelano | `VES` | | Dong Vietnamita | `VND` | | Vatu de Vanuatu | `VUV` | | Tala Samoano | `WST` | | Franco CFA Central | `XAF` | | Ouro (onça troy) | `XAU` | | Dólar do Caribe Oriental | `XCD` | | Guilder do Caribe | `XCG` | | Franco CFA Ocidental | `XOF` | | Franco CFP | `XPF` | | Rial Iemenita | `YER` | | Rand Sul-Africano | `ZAR` | | Kwacha Zambiana | `ZMW` | # 支持的货币 (/docs/cartao/currencies.zh) API 接受的货币代码，遵循 ISO 4217。在请求的货币字段中发送三字母代码。此列表反映 API 接受的集合（157 种货币）。 | 货币 | 代码 | | ----------- | ----- | | 阿联酋迪拉姆 | `AED` | | 阿富汗尼 | `AFN` | | 阿尔巴尼亚列克 | `ALL` | | 亚美尼亚德拉姆 | `AMD` | | 安哥拉宽扎 | `AOA` | | 阿根廷比索 | `ARS` | | 澳大利亚元 | `AUD` | | 阿鲁巴弗罗林 | `AWG` | | 巴巴多斯元 | `BBD` | | 孟加拉塔卡 | `BDT` | | 保加利亚列弗 | `BGN` | | 巴林第纳尔 | `BHD` | | 布隆迪法郎 | `BIF` | | 百慕大元 | `BMD` | | 文莱元 | `BND` | | 玻利维亚诺 | `BOB` | | 巴西雷亚尔 | `BRL` | | 巴哈马元 | `BSD` | | 不丹努尔特鲁姆 | `BTN` | | 博茨瓦纳普拉 | `BWP` | | 白俄罗斯卢布 | `BYN` | | 伯利兹元 | `BZD` | | 加拿大元 | `CAD` | | 刚果法郎 | `CDF` | | 瑞士法郎 | `CHF` | | 智利记账单位（UF） | `CLF` | | 智利比索 | `CLP` | | 人民币（离岸） | `CNH` | | 人民币 | `CNY` | | 哥伦比亚比索 | `COP` | | 哥伦比亚实际价值单位 | `COU` | | 哥斯达黎加科朗 | `CRC` | | 古巴比索 | `CUP` | | 佛得角埃斯库多 | `CVE` | | 捷克克朗 | `CZK` | | 吉布提法郎 | `DJF` | | 丹麦克朗 | `DKK` | | 多米尼加比索 | `DOP` | | 阿尔及利亚第纳尔 | `DZD` | | 埃及镑 | `EGP` | | 厄立特里亚纳克法 | `ERN` | | 埃塞俄比亚比尔 | `ETB` | | 欧元 | `EUR` | | 斐济元 | `FJD` | | 福克兰群岛镑 | `FKP` | | 英镑 | `GBP` | | 格鲁吉亚拉里 | `GEL` | | 加纳塞地 | `GHS` | | 直布罗陀镑 | `GIP` | | 冈比亚达拉西 | `GMD` | | 几内亚法郎 | `GNF` | | 危地马拉格查尔 | `GTQ` | | 圭亚那元 | `GYD` | | 港元 | `HKD` | | 洪都拉斯伦皮拉 | `HNL` | | 海地古德 | `HTG` | | 匈牙利福林 | `HUF` | | 印度尼西亚盾 | `IDR` | | 以色列新谢克尔 | `ILS` | | 印度卢比 | `INR` | | 伊拉克第纳尔 | `IQD` | | 伊朗里亚尔 | `IRR` | | 冰岛克朗 | `ISK` | | 牙买加元 | `JMD` | | 约旦第纳尔 | `JOD` | | 日元 | `JPY` | | 肯尼亚先令 | `KES` | | 吉尔吉斯斯坦索姆 | `KGS` | | 柬埔寨瑞尔 | `KHR` | | 科摩罗法郎 | `KMF` | | 韩元 | `KRW` | | 科威特第纳尔 | `KWD` | | 开曼群岛元 | `KYD` | | 哈萨克斯坦坚戈 | `KZT` | | 老挝基普 | `LAK` | | 黎巴嫩镑 | `LBP` | | 斯里兰卡卢比 | `LKR` | | 利比里亚元 | `LRD` | | 莱索托洛蒂 | `LSL` | | 利比亚第纳尔 | `LYD` | | 摩洛哥迪拉姆 | `MAD` | | 摩尔多瓦列伊 | `MDL` | | 马达加斯加阿里亚里 | `MGA` | | 北马其顿代纳尔 | `MKD` | | 缅甸元 | `MMK` | | 蒙古图格里克 | `MNT` | | 澳门元 | `MOP` | | 毛里塔尼亚乌吉亚（旧） | `MRO` | | 毛里塔尼亚乌吉亚 | `MRU` | | 毛里求斯卢比 | `MUR` | | 马尔代夫拉菲亚 | `MVR` | | 马拉维克瓦查 | `MWK` | | 墨西哥比索 | `MXN` | | 马来西亚林吉特 | `MYR` | | 莫桑比克梅蒂卡尔 | `MZN` | | 纳米比亚元 | `NAD` | | 尼日利亚奈拉 | `NGN` | | 尼加拉瓜科多巴 | `NIO` | | 挪威克朗 | `NOK` | | 尼泊尔卢比 | `NPR` | | 新西兰元 | `NZD` | | 阿曼里亚尔 | `OMR` | | 巴拿马巴波亚 | `PAB` | | 秘鲁索尔 | `PEN` | | 巴布亚新几内亚基那 | `PGK` | | 菲律宾比索 | `PHP` | | 巴基斯坦卢比 | `PKR` | | 波兰兹罗提 | `PLN` | | 巴拉圭瓜拉尼 | `PYG` | | 卡塔尔里亚尔 | `QAR` | | 罗马尼亚列伊 | `RON` | | 塞尔维亚第纳尔 | `RSD` | | 俄罗斯卢布 | `RUB` | | 卢旺达法郎 | `RWF` | | 沙特里亚尔 | `SAR` | | 所罗门群岛元 | `SBD` | | 塞舌尔卢比 | `SCR` | | 苏丹镑 | `SDG` | | 特别提款权 | `SDR` | | 瑞典克朗 | `SEK` | | 新加坡元 | `SGD` | | 圣赫勒拿镑 | `SHP` | | 塞拉利昂利昂 | `SLL` | | 索马里先令 | `SOS` | | 苏里南元 | `SRD` | | 南苏丹镑 | `SSP` | | 圣多美和普林西比多布拉 | `STN` | | 萨尔瓦多科朗 | `SVC` | | 叙利亚镑 | `SYP` | | 斯威士兰里兰吉尼 | `SZL` | | 泰铢 | `THB` | | 塔吉克斯坦索莫尼 | `TJS` | | 土库曼斯坦马纳特 | `TMT` | | 突尼斯第纳尔 | `TND` | | 汤加潘加 | `TOP` | | 土耳其里拉 | `TRY` | | 特立尼达和多巴哥元 | `TTD` | | 新台币 | `TWD` | | 坦桑尼亚先令 | `TZS` | | 乌克兰格里夫纳 | `UAH` | | 乌干达先令 | `UGX` | | 美元 | `USD` | | 乌拉圭比索 | `UYU` | | 乌兹别克斯坦苏姆 | `UZS` | | 委内瑞拉玻利瓦尔 | `VES` | | 越南盾 | `VND` | | 瓦努阿图瓦图 | `VUV` | | 萨摩亚塔拉 | `WST` | | 中非法郎 | `XAF` | | 黄金（金衡盎司） | `XAU` | | 东加勒比元 | `XCD` | | 加勒比盾 | `XCG` | | 西非法郎 | `XOF` | | 太平洋法郎（CFP） | `XPF` | | 也门里亚尔 | `YER` | | 南非兰特 | `ZAR` | | 赞比亚克瓦查 | `ZMW` | # Error codes (/docs/cartao/error-codes.en) Return codes provided by the acquirer in error scenarios, identifying the failure reason. In the card API they are exposed in the charge's `returnCode` and `returnMessage` fields; in the acquirer's documentation these same fields appear as `ProviderReturnCode` and `ProviderReturnMessage`. ## Acquirer codes [#acquirer-codes] | Code (`returnCode`) | Message (`returnMessage`) | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | Internal error | Data sent exceeds the field size. | | 100 | RequestId is required | Field sent is empty or invalid. | | 101 | MerchantId is required | Field sent is empty or invalid. | | 102 | Payment Type is required | Field sent is empty or invalid. | | 103 | Payment Type can only contain letters | Special characters not allowed. | | 104 | Customer Identity is required | Field sent is empty or invalid. | | 105 | Customer Name is required | Field sent is empty or invalid. | | 106 | Transaction ID is required | Field sent is empty or invalid. | | 107 | OrderId is invalid or does not exist | Field sent exceeds the size limit or contains special characters. | | 108 | Amount must be greater or equal to zero | Transaction amount must be greater than or equal to "0". | | 109 | Payment Currency is required | Field sent is empty or invalid. | | 110 | Invalid Payment Currency | Field sent is empty or invalid. | | 111 | Payment Country is required | Field sent is empty or invalid. | | 112 | Invalid Payment Country | Field sent is empty or invalid. | | 113 | Invalid Payment Code | Field sent is empty or invalid. | | 114 | The provided MerchantId is not in correct format | The MerchantId sent is not a GUID. | | 115 | The provided MerchantId was not found | The MerchantId does not exist or belongs to another environment (e.g. sandbox). | | 116 | The provided MerchantId is blocked | Store blocked, contact e-commerce support. | | 117 | Credit Card Holder is required | Field sent is empty or invalid. | | 118 | Credit Card Number is required | Field sent is empty or invalid. | | 119 | At least one Payment is required | Payment node not sent. | | 120 | Request IP not allowed. Check your IP White List | IP blocked for security reasons. | | 121 | Customer is required | Customer node not sent. | | 122 | MerchantOrderId is required | Field sent is empty or invalid. | | 123 | Installments must be greater or equal to one | Number of installments must be greater than or equal to 1. | | 124 | Credit Card is Required | Field sent is empty or invalid. | | 125 | Credit Card Expiration Date is required | Field sent is empty or invalid. | | 126 | Credit Card Expiration Date is invalid | Field sent is empty or invalid. | | 127 | You must provide CreditCard Number | Credit card number is required. | | 128 | Card Number length exceeded | Card number longer than 16 digits. | | 129 | Affiliation not found | Payment method not linked to the store or invalid Provider. | | 130 | Could not get Credit Card | \*\*\* | | 131 | MerchantKey is required | Field sent is empty or invalid. | | 132 | MerchantKey is invalid | The MerchantKey sent is not valid. | | 133 | Provider is not supported for this Payment Type | Provider sent does not exist. | | 134 | FingerPrint length exceeded | Data sent exceeds the field size. | | 135 | MerchantDefinedFieldValue length exceeded | Data sent exceeds the field size. | | 136 | ItemDataName length exceeded | Data sent exceeds the field size. | | 137 | ItemDataSKU length exceeded | Data sent exceeds the field size. | | 138 | PassengerDataName length exceeded | Data sent exceeds the field size. | | 139 | PassengerDataStatus length exceeded | Data sent exceeds the field size. | | 140 | PassengerDataEmail length exceeded | Data sent exceeds the field size. | | 141 | PassengerDataPhone length exceeded | Data sent exceeds the field size. | | 142 | TravelDataRoute length exceeded | Data sent exceeds the field size. | | 143 | TravelDataJourneyType length exceeded | Data sent exceeds the field size. | | 144 | TravelLegDataDestination length exceeded | Data sent exceeds the field size. | | 145 | TravelLegDataOrigin length exceeded | Data sent exceeds the field size. | | 146 | SecurityCode length exceeded | Data sent exceeds the field size. | | 147 | Address Street length exceeded | Data sent exceeds the field size. | | 148 | Address Number length exceeded | Data sent exceeds the field size. | | 149 | Address Complement length exceeded | Data sent exceeds the field size. | | 150 | Address ZipCode length exceeded | Data sent exceeds the field size. | | 151 | Address City length exceeded | Data sent exceeds the field size. | | 152 | Address State length exceeded | Data sent exceeds the field size. | | 153 | Address Country length exceeded | Data sent exceeds the field size. | | 154 | Address District length exceeded | Data sent exceeds the field size. | | 155 | Customer Name length exceeded | Data sent exceeds the field size. | | 156 | Customer Identity length exceeded | Data sent exceeds the field size. | | 157 | Customer IdentityType length exceeded | Data sent exceeds the field size. | | 158 | Customer Email length exceeded | Data sent exceeds the field size. | | 159 | ExtraData Name length exceeded | Data sent exceeds the field size. | | 160 | ExtraData Value length exceeded | Data sent exceeds the field size. | | 161 | Boleto Instructions length exceeded | Data sent exceeds the field size. | | 162 | Boleto Demostrative length exceeded | Data sent exceeds the field size. | | 163 | Return Url is required | Return URL is not valid. Pagination or extensions (e.g. PHP) are not accepted in the return URL. | | 166 | AuthorizeNow is required | \*\*\* | | 167 | Antifraud not configured | Antifraud not linked to the merchant's registration. | | 168 | Recurrent Payment not found | Recurrence not found. | | 169 | Recurrent Payment is not active | Recurrence is not active. Execution halted. | | 170 | Cartão Protegido not configured | Protected card not linked to the merchant's registration. | | 171 | Affiliation data not sent | Order processing failure, contact e-commerce support. | | 172 | Credential Code is required | Failure validating the credentials sent. | | 173 | Payment method is not enabled | Payment method not linked to the merchant's registration. | | 174 | Card Number is required | Field sent is empty or invalid. | | 175 | EAN is required | Field sent is empty or invalid. | | 176 | Payment Currency is not supported | Field sent is empty or invalid. | | 177 | Card Number is invalid | Field sent is empty or invalid. | | 178 | EAN is invalid | Field sent is empty or invalid. | | 179 | The max number of installments allowed for recurring payment is 1 | Field sent is empty or invalid. | | 180 | The provided Card PaymentToken was not found | Protected card token not found. | | 181 | The MerchantIdJustClick is not configured | Protected card token blocked. | | 182 | Brand is required | Card brand not sent. | | 183 | Invalid customer bithdate | Invalid or future birth date. | | 184 | Request could not be empty | Request format failure. Check the code sent. | | 185 | Brand is not supported by selected provider | Brand not supported by the Payment Gateway API. | | 186 | The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments) | Payment method does not support the command sent. | | 187 | ExtraData Collection contains one or more duplicated names | \*\*\* | | 188 | Avs with CPF invalid | \*\*\* | | 189 | Avs with length of street exceeded | Data sent exceeds the field size. | | 190 | Avs with length of number/complement exceeded | Data sent exceeds the field size (address number or complement). | | 191 | Avs with length of district exceeded | Data sent exceeds the field size. | | 192 | Avs with zip code invalid | ZIP code sent is invalid. | | 193 | Split Amount must be greater than zero | Amount for the SPLIT must be greater than 0. | | 194 | Split Establishment is Required | SPLIT not enabled for the store's registration. | | 195 | PlatformId is required | Platform validator not sent. | | 196 | DeliveryAddress is required | Required field not sent. | | 197 | Street is required | Required field not sent. | | 198 | Number is required | Required field not sent. | | 199 | ZipCode is required | Required field not sent. | | 200 | City is required | Required field not sent. | | 201 | State is required | Required field not sent. | | 202 | District is required | Required field not sent. | | 203 | Cart item name is required | Required field not sent. | | 204 | Cart item quantity is required | Required field not sent. | | 205 | Cart item type is required | Required field not sent. | | 206 | Cart item name length exceeded | Data sent exceeds the field size. | | 207 | Cart item description length exceeded | Data sent exceeds the field size. | | 208 | Cart item sku length exceeded | Data sent exceeds the field size. | | 209 | Shipping addressee sku length exceeded | Data sent exceeds the field size. | | 210 | Shipping data cannot be null | Required field not sent. | | 213 | Credit Card Number is invalid | Credit card sent is invalid. | | 214 | Credit Card Holder Must Have Only Letters | Card holder must not contain special characters. | | 215 | Agency is required in Boleto Credential | Required field not sent. | | 216 | Customer IP address is invalid | IP blocked for security reasons. | | 300 | MerchantId was not found | \*\*\* | | 301 | Request IP is not allowed | \*\*\* | | 302 | Sent MerchantOrderId is duplicated | The order was duplicated. | | 303 | Sent OrderId does not exist | \*\*\* | | 304 | Customer Identity is required | \*\*\* | | 306 | Merchant is blocked | \*\*\* | | 307 | Transaction not found | Transaction not found or nonexistent in the environment. | | 308 | Transaction not available to capture | Transaction cannot be captured. Contact e-commerce support.
\*Check whether the amount provided is lower than the total transaction amount or whether it is available for capture | | 309 | Transaction not available to void | Transaction cannot be voided. Contact e-commerce support. | | 310 | Payment method does not support this operation | Command sent not supported by the payment method. | | 311 | Refund is not enabled for this merchant | Cancellation after 24 hours not enabled for the merchant. | | 312 | Transaction not available to refund | Transaction does not allow cancellation after 24 hours. | | 313 | Recurrent Payment not found | Recurring transaction not found or not available in the environment. | | 314 | Invalid Integration | \*\*\* | | 315 | Cannot change NextRecurrency with pending payment | \*\*\* | | 316 | Cannot set NextRecurrency to past date | Changing the recurrence date to a past date is not allowed. | | 317 | Invalid Recurrency Day | \*\*\* | | 318 | No transaction found | \*\*\* | | 319 | Smart Recurrency is not enabled | Recurrence not linked to the merchant's registration. | | 320 | Cannot Update Affiliation because this recurrency has no affiliation saved | \*\*\* | | 321 | Cannot Set EndDate to before next recurrency | \*\*\* | | 322 | Zero Dollar Auth is not enabled | Zero Dollar not linked to the merchant's registration. | | 323 | Bin Query is not enabled | BIN lookup not linked to the merchant's registration. | ## Other error codes [#other-error-codes] The following codes are returned when communication between the API and the acquirer fails (such as timeouts) or due to integration problems. If communication with the acquirer fails, the transaction may still have been approved, and the status is reconciled automatically afterwards. To receive the update, register a status change notification URL or query the status via the API. Below are some of the codes returned: | Code | Meaning | | ----- | ---------------------------------------------------------- | | BP171 | Rejected due to fraud risk (Velocity) | | BP335 | Canceled due to a transactional error in the Payment Split | | BP900 | Operation failure | | BP901 | Operation failure | | BP902 | Wait for the response of the previous operation | | BP903 | Void failure | | BP904 | Query failure | BP codes are returned by the acquirer; if there is any divergence, confirm with support. # Códigos de erro (/docs/cartao/error-codes) Códigos de retorno fornecidos pela adquirente em casos de erro, identificando o motivo da falha. Na API de cartão eles são expostos nos campos `returnCode` e `returnMessage` da cobrança; na documentação da adquirente esses mesmos campos aparecem como `ProviderReturnCode` e `ProviderReturnMessage`. ## Códigos da adquirente [#códigos-da-adquirente] | Código (`returnCode`) | Mensagem (`returnMessage`) | Descrição | | --------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | Internal error | Dado enviado excede o tamanho do campo. | | 100 | RequestId is required | Campo enviado está vazio ou inválido. | | 101 | MerchantId is required | Campo enviado está vazio ou inválido. | | 102 | Payment Type is required | Campo enviado está vazio ou inválido. | | 103 | Payment Type can only contain letters | Caracteres especiais não permitidos. | | 104 | Customer Identity is required | Campo enviado está vazio ou inválido. | | 105 | Customer Name is required | Campo enviado está vazio ou inválido. | | 106 | Transaction ID is required | Campo enviado está vazio ou inválido. | | 107 | OrderId is invalid or does not exist | Campo enviado excede o tamanho ou contém caracteres especiais. | | 108 | Amount must be greater or equal to zero | Valor da transação deve ser maior ou igual a "0". | | 109 | Payment Currency is required | Campo enviado está vazio ou inválido. | | 110 | Invalid Payment Currency | Campo enviado está vazio ou inválido. | | 111 | Payment Country is required | Campo enviado está vazio ou inválido. | | 112 | Invalid Payment Country | Campo enviado está vazio ou inválido. | | 113 | Invalid Payment Code | Campo enviado está vazio ou inválido. | | 114 | The provided MerchantId is not in correct format | O MerchantId enviado não é um GUID. | | 115 | The provided MerchantId was not found | O MerchantId não existe ou pertence a outro ambiente (ex.: sandbox). | | 116 | The provided MerchantId is blocked | Loja bloqueada, entre em contato com o suporte e-commerce. | | 117 | Credit Card Holder is required | Campo enviado está vazio ou inválido. | | 118 | Credit Card Number is required | Campo enviado está vazio ou inválido. | | 119 | At least one Payment is required | Nó Payment não enviado. | | 120 | Request IP not allowed. Check your IP White List | IP bloqueado por questões de segurança. | | 121 | Customer is required | Nó Customer não enviado. | | 122 | MerchantOrderId is required | Campo enviado está vazio ou inválido. | | 123 | Installments must be greater or equal to one | Número de parcelas deve ser maior ou igual a 1. | | 124 | Credit Card is Required | Campo enviado está vazio ou inválido. | | 125 | Credit Card Expiration Date is required | Campo enviado está vazio ou inválido. | | 126 | Credit Card Expiration Date is invalid | Campo enviado está vazio ou inválido. | | 127 | You must provide CreditCard Number | Número do cartão de crédito é obrigatório. | | 128 | Card Number length exceeded | Número do cartão superior a 16 dígitos. | | 129 | Affiliation not found | Meio de pagamento não vinculado à loja ou Provider inválido. | | 130 | Could not get Credit Card | \*\*\* | | 131 | MerchantKey is required | Campo enviado está vazio ou inválido. | | 132 | MerchantKey is invalid | O MerchantKey enviado não é válido. | | 133 | Provider is not supported for this Payment Type | Provider enviado não existe. | | 134 | FingerPrint length exceeded | Dado enviado excede o tamanho do campo. | | 135 | MerchantDefinedFieldValue length exceeded | Dado enviado excede o tamanho do campo. | | 136 | ItemDataName length exceeded | Dado enviado excede o tamanho do campo. | | 137 | ItemDataSKU length exceeded | Dado enviado excede o tamanho do campo. | | 138 | PassengerDataName length exceeded | Dado enviado excede o tamanho do campo. | | 139 | PassengerDataStatus length exceeded | Dado enviado excede o tamanho do campo. | | 140 | PassengerDataEmail length exceeded | Dado enviado excede o tamanho do campo. | | 141 | PassengerDataPhone length exceeded | Dado enviado excede o tamanho do campo. | | 142 | TravelDataRoute length exceeded | Dado enviado excede o tamanho do campo. | | 143 | TravelDataJourneyType length exceeded | Dado enviado excede o tamanho do campo. | | 144 | TravelLegDataDestination length exceeded | Dado enviado excede o tamanho do campo. | | 145 | TravelLegDataOrigin length exceeded | Dado enviado excede o tamanho do campo. | | 146 | SecurityCode length exceeded | Dado enviado excede o tamanho do campo. | | 147 | Address Street length exceeded | Dado enviado excede o tamanho do campo. | | 148 | Address Number length exceeded | Dado enviado excede o tamanho do campo. | | 149 | Address Complement length exceeded | Dado enviado excede o tamanho do campo. | | 150 | Address ZipCode length exceeded | Dado enviado excede o tamanho do campo. | | 151 | Address City length exceeded | Dado enviado excede o tamanho do campo. | | 152 | Address State length exceeded | Dado enviado excede o tamanho do campo. | | 153 | Address Country length exceeded | Dado enviado excede o tamanho do campo. | | 154 | Address District length exceeded | Dado enviado excede o tamanho do campo. | | 155 | Customer Name length exceeded | Dado enviado excede o tamanho do campo. | | 156 | Customer Identity length exceeded | Dado enviado excede o tamanho do campo. | | 157 | Customer IdentityType length exceeded | Dado enviado excede o tamanho do campo. | | 158 | Customer Email length exceeded | Dado enviado excede o tamanho do campo. | | 159 | ExtraData Name length exceeded | Dado enviado excede o tamanho do campo. | | 160 | ExtraData Value length exceeded | Dado enviado excede o tamanho do campo. | | 161 | Boleto Instructions length exceeded | Dado enviado excede o tamanho do campo. | | 162 | Boleto Demostrative length exceeded | Dado enviado excede o tamanho do campo. | | 163 | Return Url is required | URL de retorno não é válida. Não são aceitas paginação ou extensões (ex.: PHP) na URL de retorno. | | 166 | AuthorizeNow is required | \*\*\* | | 167 | Antifraud not configured | Antifraude não vinculado ao cadastro do lojista. | | 168 | Recurrent Payment not found | Recorrência não encontrada. | | 169 | Recurrent Payment is not active | Recorrência não está ativa. Execução paralisada. | | 170 | Cartão Protegido not configured | Cartão protegido não vinculado ao cadastro do lojista. | | 171 | Affiliation data not sent | Falha no processamento do pedido, entre em contato com o suporte e-commerce. | | 172 | Credential Code is required | Falha na validação das credenciadas enviadas. | | 173 | Payment method is not enabled | Meio de pagamento não vinculado ao cadastro do lojista. | | 174 | Card Number is required | Campo enviado está vazio ou inválido. | | 175 | EAN is required | Campo enviado está vazio ou inválido. | | 176 | Payment Currency is not supported | Campo enviado está vazio ou inválido. | | 177 | Card Number is invalid | Campo enviado está vazio ou inválido. | | 178 | EAN is invalid | Campo enviado está vazio ou inválido. | | 179 | The max number of installments allowed for recurring payment is 1 | Campo enviado está vazio ou inválido. | | 180 | The provided Card PaymentToken was not found | Token do cartão protegido não encontrado. | | 181 | The MerchantIdJustClick is not configured | Token do cartão protegido bloqueado. | | 182 | Brand is required | Bandeira do cartão não enviada. | | 183 | Invalid customer bithdate | Data de nascimento inválida ou futura. | | 184 | Request could not be empty | Falha no formato da requisição. Verifique o código enviado. | | 185 | Brand is not supported by selected provider | Bandeira não suportada pela API Gateway de Pagamento. | | 186 | The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments) | Meio de pagamento não suporta o comando enviado. | | 187 | ExtraData Collection contains one or more duplicated names | \*\*\* | | 188 | Avs with CPF invalid | \*\*\* | | 189 | Avs with length of street exceeded | Dado enviado excede o tamanho do campo. | | 190 | Avs with length of number/complement exceeded | Dado enviado excede o tamanho do campo (número ou complemento do endereço). | | 191 | Avs with length of district exceeded | Dado enviado excede o tamanho do campo. | | 192 | Avs with zip code invalid | CEP enviado é inválido. | | 193 | Split Amount must be greater than zero | Valor para realização do SPLIT deve ser superior a 0. | | 194 | Split Establishment is Required | SPLIT não habilitado para o cadastro da loja. | | 195 | PlatformId is required | Validador de plataformas não enviado. | | 196 | DeliveryAddress is required | Campo obrigatório não enviado. | | 197 | Street is required | Campo obrigatório não enviado. | | 198 | Number is required | Campo obrigatório não enviado. | | 199 | ZipCode is required | Campo obrigatório não enviado. | | 200 | City is required | Campo obrigatório não enviado. | | 201 | State is required | Campo obrigatório não enviado. | | 202 | District is required | Campo obrigatório não enviado. | | 203 | Cart item name is required | Campo obrigatório não enviado. | | 204 | Cart item quantity is required | Campo obrigatório não enviado. | | 205 | Cart item type is required | Campo obrigatório não enviado. | | 206 | Cart item name length exceeded | Dado enviado excede o tamanho do campo. | | 207 | Cart item description length exceeded | Dado enviado excede o tamanho do campo. | | 208 | Cart item sku length exceeded | Dado enviado excede o tamanho do campo. | | 209 | Shipping addressee sku length exceeded | Dado enviado excede o tamanho do campo. | | 210 | Shipping data cannot be null | Campo obrigatório não enviado. | | 213 | Credit Card Number is invalid | Cartão de crédito enviado é inválido. | | 214 | Credit Card Holder Must Have Only Letters | Portador do cartão não deve conter caracteres especiais. | | 215 | Agency is required in Boleto Credential | Campo obrigatório não enviado. | | 216 | Customer IP address is invalid | IP bloqueado por questões de segurança. | | 300 | MerchantId was not found | \*\*\* | | 301 | Request IP is not allowed | \*\*\* | | 302 | Sent MerchantOrderId is duplicated | Houve duplicidade do pedido. | | 303 | Sent OrderId does not exist | \*\*\* | | 304 | Customer Identity is required | \*\*\* | | 306 | Merchant is blocked | \*\*\* | | 307 | Transaction not found | Transação não encontrada ou não existente no ambiente. | | 308 | Transaction not available to capture | Transação não pode ser capturada. Entre em contato com o suporte e-commerce.
\*Verificar se o valor informado é inferior ao valor total da transação ou se está disponível para captura | | 309 | Transaction not available to void | Transação não pode ser cancelada. Entre em contato com o suporte e-commerce. | | 310 | Payment method does not support this operation | Comando enviado não suportado pelo meio de pagamento. | | 311 | Refund is not enabled for this merchant | Cancelamento após 24 horas não liberado para o lojista. | | 312 | Transaction not available to refund | Transação não permite cancelamento após 24 horas. | | 313 | Recurrent Payment not found | Transação recorrente não encontrada ou não disponível no ambiente. | | 314 | Invalid Integration | \*\*\* | | 315 | Cannot change NextRecurrency with pending payment | \*\*\* | | 316 | Cannot set NextRecurrency to past date | Não é permitido alterar a data da recorrência para uma data passada. | | 317 | Invalid Recurrency Day | \*\*\* | | 318 | No transaction found | \*\*\* | | 319 | Smart Recurrency is not enabled | Recorrência não vinculada ao cadastro do lojista. | | 320 | Cannot Update Affiliation because this recurrency has no affiliation saved | \*\*\* | | 321 | Cannot Set EndDate to before next recurrency | \*\*\* | | 322 | Zero Dollar Auth is not enabled | Zero Dollar não vinculado ao cadastro do lojista. | | 323 | Bin Query is not enabled | Consulta de Bins não vinculada ao cadastro do lojista. | ## Outros códigos de erro [#outros-códigos-de-erro] Os códigos a seguir são retornados em casos de falha na comunicação entre a API e a adquirente (como timeouts) ou devido a problemas na integração. Em caso de falha de comunicação com a adquirente, a transação pode ainda assim ter sido aprovada, e o status é reconciliado automaticamente depois. Para receber a atualização, cadastre uma URL de notificação de mudança de status ou consulte o status pela API. Abaixo, alguns dos códigos retornados: | Código | Significado | | ------ | ----------------------------------------------------------------------------------------------------------- | | BP171 | Rejeitado por risco de fraude (Velocity) | | BP335 | Cancelado por erro transacional no Split de Pagamento | | BP900 | Falha na operação | | BP901 | Falha na operação | | BP902 | Espere pela resposta da operação anterior (também documentado como "Aguarde resposta da operação anterior") | | BP903 | Falha no cancelamento | | BP904 | Falha na consulta | Códigos BP são retornados pela adquirente; em caso de divergência confirme com o suporte. # 错误代码 (/docs/cartao/error-codes.zh) 收单机构在出错时提供的返回代码，用于标识失败原因。在卡 API 中，它们通过收款的 `returnCode` 和 `returnMessage` 字段暴露；在收单机构的文档中，这些字段对应 `ProviderReturnCode` 和 `ProviderReturnMessage`。 ## 收单机构代码 [#收单机构代码] | 代码（`returnCode`） | 消息（`returnMessage`） | 描述 | | ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | 0 | Internal error | 发送的数据超出字段长度限制。 | | 100 | RequestId is required | 发送的字段为空或无效。 | | 101 | MerchantId is required | 发送的字段为空或无效。 | | 102 | Payment Type is required | 发送的字段为空或无效。 | | 103 | Payment Type can only contain letters | 不允许使用特殊字符。 | | 104 | Customer Identity is required | 发送的字段为空或无效。 | | 105 | Customer Name is required | 发送的字段为空或无效。 | | 106 | Transaction ID is required | 发送的字段为空或无效。 | | 107 | OrderId is invalid or does not exist | 发送的字段超出长度限制或包含特殊字符。 | | 108 | Amount must be greater or equal to zero | 交易金额必须大于或等于“0”。 | | 109 | Payment Currency is required | 发送的字段为空或无效。 | | 110 | Invalid Payment Currency | 发送的字段为空或无效。 | | 111 | Payment Country is required | 发送的字段为空或无效。 | | 112 | Invalid Payment Country | 发送的字段为空或无效。 | | 113 | Invalid Payment Code | 发送的字段为空或无效。 | | 114 | The provided MerchantId is not in correct format | 发送的 MerchantId 不是 GUID。 | | 115 | The provided MerchantId was not found | MerchantId 不存在或属于其他环境（例如 sandbox）。 | | 116 | The provided MerchantId is blocked | 店铺已被冻结，请联系电商支持团队。 | | 117 | Credit Card Holder is required | 发送的字段为空或无效。 | | 118 | Credit Card Number is required | 发送的字段为空或无效。 | | 119 | At least one Payment is required | 未发送 Payment 节点。 | | 120 | Request IP not allowed. Check your IP White List | 出于安全原因该 IP 已被拦截。 | | 121 | Customer is required | 未发送 Customer 节点。 | | 122 | MerchantOrderId is required | 发送的字段为空或无效。 | | 123 | Installments must be greater or equal to one | 分期数必须大于或等于 1。 | | 124 | Credit Card is Required | 发送的字段为空或无效。 | | 125 | Credit Card Expiration Date is required | 发送的字段为空或无效。 | | 126 | Credit Card Expiration Date is invalid | 发送的字段为空或无效。 | | 127 | You must provide CreditCard Number | 信用卡卡号为必填项。 | | 128 | Card Number length exceeded | 卡号超过 16 位。 | | 129 | Affiliation not found | 支付方式未绑定到店铺，或 Provider 无效。 | | 130 | Could not get Credit Card | \*\*\* | | 131 | MerchantKey is required | 发送的字段为空或无效。 | | 132 | MerchantKey is invalid | 发送的 MerchantKey 无效。 | | 133 | Provider is not supported for this Payment Type | 发送的 Provider 不存在。 | | 134 | FingerPrint length exceeded | 发送的数据超出字段长度限制。 | | 135 | MerchantDefinedFieldValue length exceeded | 发送的数据超出字段长度限制。 | | 136 | ItemDataName length exceeded | 发送的数据超出字段长度限制。 | | 137 | ItemDataSKU length exceeded | 发送的数据超出字段长度限制。 | | 138 | PassengerDataName length exceeded | 发送的数据超出字段长度限制。 | | 139 | PassengerDataStatus length exceeded | 发送的数据超出字段长度限制。 | | 140 | PassengerDataEmail length exceeded | 发送的数据超出字段长度限制。 | | 141 | PassengerDataPhone length exceeded | 发送的数据超出字段长度限制。 | | 142 | TravelDataRoute length exceeded | 发送的数据超出字段长度限制。 | | 143 | TravelDataJourneyType length exceeded | 发送的数据超出字段长度限制。 | | 144 | TravelLegDataDestination length exceeded | 发送的数据超出字段长度限制。 | | 145 | TravelLegDataOrigin length exceeded | 发送的数据超出字段长度限制。 | | 146 | SecurityCode length exceeded | 发送的数据超出字段长度限制。 | | 147 | Address Street length exceeded | 发送的数据超出字段长度限制。 | | 148 | Address Number length exceeded | 发送的数据超出字段长度限制。 | | 149 | Address Complement length exceeded | 发送的数据超出字段长度限制。 | | 150 | Address ZipCode length exceeded | 发送的数据超出字段长度限制。 | | 151 | Address City length exceeded | 发送的数据超出字段长度限制。 | | 152 | Address State length exceeded | 发送的数据超出字段长度限制。 | | 153 | Address Country length exceeded | 发送的数据超出字段长度限制。 | | 154 | Address District length exceeded | 发送的数据超出字段长度限制。 | | 155 | Customer Name length exceeded | 发送的数据超出字段长度限制。 | | 156 | Customer Identity length exceeded | 发送的数据超出字段长度限制。 | | 157 | Customer IdentityType length exceeded | 发送的数据超出字段长度限制。 | | 158 | Customer Email length exceeded | 发送的数据超出字段长度限制。 | | 159 | ExtraData Name length exceeded | 发送的数据超出字段长度限制。 | | 160 | ExtraData Value length exceeded | 发送的数据超出字段长度限制。 | | 161 | Boleto Instructions length exceeded | 发送的数据超出字段长度限制。 | | 162 | Boleto Demostrative length exceeded | 发送的数据超出字段长度限制。 | | 163 | Return Url is required | 回调 URL 无效。回调 URL 中不接受分页参数或扩展名（例如 PHP）。 | | 166 | AuthorizeNow is required | \*\*\* | | 167 | Antifraud not configured | 反欺诈服务未绑定到商户档案。 | | 168 | Recurrent Payment not found | 未找到循环扣款。 | | 169 | Recurrent Payment is not active | 循环扣款未处于激活状态，执行已暂停。 | | 170 | Cartão Protegido not configured | Cartão Protegido（受保护卡）未绑定到商户档案。 | | 171 | Affiliation data not sent | 订单处理失败，请联系电商支持团队。 | | 172 | Credential Code is required | 发送的凭据验证失败。 | | 173 | Payment method is not enabled | 支付方式未绑定到商户档案。 | | 174 | Card Number is required | 发送的字段为空或无效。 | | 175 | EAN is required | 发送的字段为空或无效。 | | 176 | Payment Currency is not supported | 发送的字段为空或无效。 | | 177 | Card Number is invalid | 发送的字段为空或无效。 | | 178 | EAN is invalid | 发送的字段为空或无效。 | | 179 | The max number of installments allowed for recurring payment is 1 | 发送的字段为空或无效。 | | 180 | The provided Card PaymentToken was not found | 未找到受保护卡的 token。 | | 181 | The MerchantIdJustClick is not configured | 受保护卡的 token 已被冻结。 | | 182 | Brand is required | 未发送卡组织信息。 | | 183 | Invalid customer bithdate | 出生日期无效或为未来日期。 | | 184 | Request could not be empty | 请求格式错误，请检查发送的代码。 | | 185 | Brand is not supported by selected provider | 支付网关 API 不支持该卡组织。 | | 186 | The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments) | 支付方式不支持发送的指令。 | | 187 | ExtraData Collection contains one or more duplicated names | \*\*\* | | 188 | Avs with CPF invalid | \*\*\* | | 189 | Avs with length of street exceeded | 发送的数据超出字段长度限制。 | | 190 | Avs with length of number/complement exceeded | 发送的数据超出字段长度限制（地址门牌号或补充信息）。 | | 191 | Avs with length of district exceeded | 发送的数据超出字段长度限制。 | | 192 | Avs with zip code invalid | 发送的邮政编码（CEP）无效。 | | 193 | Split Amount must be greater than zero | SPLIT 分账金额必须大于 0。 | | 194 | Split Establishment is Required | 店铺档案未启用 SPLIT 分账。 | | 195 | PlatformId is required | 未发送平台校验标识。 | | 196 | DeliveryAddress is required | 未发送必填字段。 | | 197 | Street is required | 未发送必填字段。 | | 198 | Number is required | 未发送必填字段。 | | 199 | ZipCode is required | 未发送必填字段。 | | 200 | City is required | 未发送必填字段。 | | 201 | State is required | 未发送必填字段。 | | 202 | District is required | 未发送必填字段。 | | 203 | Cart item name is required | 未发送必填字段。 | | 204 | Cart item quantity is required | 未发送必填字段。 | | 205 | Cart item type is required | 未发送必填字段。 | | 206 | Cart item name length exceeded | 发送的数据超出字段长度限制。 | | 207 | Cart item description length exceeded | 发送的数据超出字段长度限制。 | | 208 | Cart item sku length exceeded | 发送的数据超出字段长度限制。 | | 209 | Shipping addressee sku length exceeded | 发送的数据超出字段长度限制。 | | 210 | Shipping data cannot be null | 未发送必填字段。 | | 213 | Credit Card Number is invalid | 发送的信用卡无效。 | | 214 | Credit Card Holder Must Have Only Letters | 持卡人姓名不得包含特殊字符。 | | 215 | Agency is required in Boleto Credential | 未发送必填字段。 | | 216 | Customer IP address is invalid | 出于安全原因该 IP 已被拦截。 | | 300 | MerchantId was not found | \*\*\* | | 301 | Request IP is not allowed | \*\*\* | | 302 | Sent MerchantOrderId is duplicated | 订单出现重复。 | | 303 | Sent OrderId does not exist | \*\*\* | | 304 | Customer Identity is required | \*\*\* | | 306 | Merchant is blocked | \*\*\* | | 307 | Transaction not found | 未找到交易，或交易在该环境中不存在。 | | 308 | Transaction not available to capture | 交易无法请款，请联系电商支持团队。
\*请检查所填金额是否低于交易总额，或交易是否可请款 | | 309 | Transaction not available to void | 交易无法撤销，请联系电商支持团队。 | | 310 | Payment method does not support this operation | 支付方式不支持发送的指令。 | | 311 | Refund is not enabled for this merchant | 商户未开通 24 小时后的退款功能。 | | 312 | Transaction not available to refund | 该交易不允许在 24 小时后退款。 | | 313 | Recurrent Payment not found | 未找到循环扣款交易，或其在该环境中不可用。 | | 314 | Invalid Integration | \*\*\* | | 315 | Cannot change NextRecurrency with pending payment | \*\*\* | | 316 | Cannot set NextRecurrency to past date | 不允许将循环扣款日期改为过去的日期。 | | 317 | Invalid Recurrency Day | \*\*\* | | 318 | No transaction found | \*\*\* | | 319 | Smart Recurrency is not enabled | 循环扣款功能未绑定到商户档案。 | | 320 | Cannot Update Affiliation because this recurrency has no affiliation saved | \*\*\* | | 321 | Cannot Set EndDate to before next recurrency | \*\*\* | | 322 | Zero Dollar Auth is not enabled | Zero Dollar 未绑定到商户档案。 | | 323 | Bin Query is not enabled | BIN 查询功能未绑定到商户档案。 | ## 其他错误代码 [#其他错误代码] 以下代码在 API 与收单机构之间通信失败（如超时）或集成出现问题时返回。 与收单机构通信失败时，交易仍有可能已获批准，状态会在之后自动对账。若要接收更新，请登记状态变更通知 URL，或通过 API 查询状态。 以下是部分返回的代码： | 代码 | 含义 | | ----- | ------------------- | | BP171 | 因欺诈风险被拒绝（Velocity） | | BP335 | 因支付分账（Split）交易错误被取消 | | BP900 | 操作失败 | | BP901 | 操作失败 | | BP902 | 请等待上一操作的响应 | | BP903 | 撤销失败 | | BP904 | 查询失败 | BP 代码由收单机构返回；如有差异，请与支持团队确认。 # Getting started (/docs/cartao/getting-started.en) In this guide we use the **sandbox** (`https://api.sandbox.payzu.io/v1`). In production the base URL is `https://api.payzu.io/v1`. ### Prerequisites [#prerequisites] Before your first call you need two items, both provided by the PayZu team: * **Client mTLS certificate** (`cliente.crt`, `cliente.key` and `ca.pem`). Install the certificate and configure your system to use it on **every** API call, always over HTTPS. Details in [Authentication](/docs/cartao/authentication). * **Credentials** `client_id` and `client_secret`, used to obtain the access token. ### Get the token [#get-the-token] Call [`POST /token`](/docs/cartao/endpoints/token/post_token) using **Basic Auth** with `client_id` and `client_secret`, along with the mTLS certificate, and use the returned `access_token` as the Bearer token on the next calls. For the full request and response example, see [Authentication](/docs/cartao/authentication). ### Create the first charge [#create-the-first-charge] Create a charge via [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). The required fields are `amount`, `customer`, `paymentType`, `cart`, `creditCardPayment` and `externalId`. Full schema in the reference. ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/charges \ --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "amount": 10000, "externalId": "order-2026-0001", "paymentType": "creditcard", "customer": { "name": "John Smith" }, "cart": [ { "name": "Monthly plan", "quantity": 1, "sku": "PLAN-01", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "JOAO DA SILVA", "expiration": "12/2030", "cvv": "123" } } }' ``` In production, switch the base URL to `https://api.payzu.io/v1`. Monetary values (`amount`, `unitPrice`) are always in **cents**. `10000` equals R$ 100.00. With `authenticate: false` the buyer is not redirected to the issuer for authentication. For authenticated flows, see [3D Secure](/docs/cartao/three-d-secure). ### Read the response [#read-the-response] The response contains the charge `id`, the `externalId` you provided and the `creditCardPayment` object with `status`, `reasonCode` and `reasonMessage`. The main statuses: | Code | Status | Meaning | | ---- | ---------------- | -------------------------------------------------------------------- | | 1 | Authorized | Approved by the issuer, eligible for capture, but not yet completed. | | 2 | PaymentConfirmed | Payment confirmed and finalized. | | 3 | Denied | Payment denied by an authorizer. | If `creditCardPayment.status` returned `2` (PaymentConfirmed), your first charge is confirmed. The full list of codes is in [Transaction status](/docs/cartao/transaction-status). ### Test scenarios and configure webhooks [#test-scenarios-and-configure-webhooks] To simulate approvals, denials and timeouts in the sandbox, use the [test cards](/docs/cartao/test-cards): the last digits of the card number determine the transaction outcome. To receive notifications about the charge status without polling the API, provide a `postbackUrl` when creating the charge. Payload structure and validation in [Webhooks](/docs/cartao/webhooks). ## Next steps [#next-steps] # Primeiros passos (/docs/cartao/getting-started) Neste guia usamos o **sandbox** (`https://api.sandbox.payzu.io/v1`). Em produção a base URL é `https://api.payzu.io/v1`. ### Pré-requisitos [#pré-requisitos] Antes da primeira chamada você precisa de dois itens, ambos fornecidos pela equipe PayZu: * **Certificado mTLS de cliente** (`cliente.crt`, `cliente.key` e `ca.pem`). Instale o certificado e configure seu sistema para utilizá-lo em **todas** as chamadas à API, sempre por HTTPS. Detalhes em [Autenticação](/docs/cartao/authentication). * **Credenciais** `client_id` e `client_secret`, usadas para obter o token de acesso. ### Obter o token [#obter-o-token] Chame [`POST /token`](/docs/cartao/endpoints/token/post_token) usando **Basic Auth** com `client_id` e `client_secret`, junto do certificado mTLS, e use o `access_token` retornado como Bearer token nas próximas chamadas. Para o exemplo completo de requisição e resposta, veja [Autenticação](/docs/cartao/authentication). ### Criar a primeira cobrança [#criar-a-primeira-cobrança] Crie uma cobrança via [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). Os campos obrigatórios são `amount`, `customer`, `paymentType`, `cart`, `creditCardPayment` e `externalId`. Schema completo na referência. ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/charges \ --header "Authorization: Bearer SEU_ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "amount": 10000, "externalId": "pedido-2026-0001", "paymentType": "creditcard", "customer": { "name": "João da Silva" }, "cart": [ { "name": "Plano mensal", "quantity": 1, "sku": "PLANO-01", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "JOAO DA SILVA", "expiration": "12/2030", "cvv": "123" } } }' ``` Em produção, troque a base URL para `https://api.payzu.io/v1`. Valores monetários (`amount`, `unitPrice`) são sempre em **centavos**. `10000` equivale a R$ 100,00. Com `authenticate: false` o comprador não é direcionado ao emissor para autenticação. Para fluxos autenticados, veja [3D Secure](/docs/cartao/three-d-secure). ### Ler a resposta [#ler-a-resposta] A resposta traz o `id` da cobrança, o `externalId` informado e o objeto `creditCardPayment` com `status`, `reasonCode` e `reasonMessage`. Os principais status: | Código | Status | Significado | | ------ | ---------------- | --------------------------------------------------------------------- | | 1 | Authorized | Aprovado pelo emissor, apto a ser capturado, mas ainda não concluído. | | 2 | PaymentConfirmed | Pagamento confirmado e finalizado. | | 3 | Denied | Pagamento negado por autorizador. | Se `creditCardPayment.status` retornou `2` (PaymentConfirmed), sua primeira cobrança está confirmada. A lista completa de códigos está em [Status da transação](/docs/cartao/transaction-status). ### Testar cenários e configurar webhooks [#testar-cenários-e-configurar-webhooks] Para simular aprovações, negativas e time out no sandbox, use os [cartões de teste](/docs/cartao/test-cards): os últimos dígitos do número do cartão determinam o resultado da transação. Para receber notificações sobre o status da cobrança sem precisar consultar a API, informe uma `postbackUrl` na criação da cobrança. Estrutura do payload e validação em [Webhooks](/docs/cartao/webhooks). ## Próximos passos [#próximos-passos] # 快速开始 (/docs/cartao/getting-started.zh) 本指南使用 **sandbox**(`https://api.sandbox.payzu.io/v1`)。生产环境的基础 URL 为 `https://api.payzu.io/v1`。 ### 前提条件 [#前提条件] 在发起第一次调用之前,您需要准备两项内容,均由 PayZu 团队提供: * **客户端 mTLS 证书**(`cliente.crt`、`cliente.key` 和 `ca.pem`)。请安装证书并配置您的系统,在**所有** API 调用中使用它,且始终通过 HTTPS。详见[身份认证](/docs/cartao/authentication)。 * **凭证** `client_id` 和 `client_secret`,用于获取访问 token。 ### 获取 token [#获取-token] 使用 `client_id` 和 `client_secret` 通过 **Basic Auth** 调用 [`POST /token`](/docs/cartao/endpoints/token/post_token),并附带 mTLS 证书,然后在后续调用中将返回的 `access_token` 作为 Bearer token 使用。完整的请求和响应示例见[身份认证](/docs/cartao/authentication)。 ### 创建第一笔收款 [#创建第一笔收款] 通过 [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) 创建收款。必填字段为 `amount`、`customer`、`paymentType`、`cart`、`creditCardPayment` 和 `externalId`。完整 schema 见接口参考。 ```bash curl --request POST \ --url https://api.sandbox.payzu.io/v1/charges \ --header "Authorization: Bearer SEU_ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ --data '{ "amount": 10000, "externalId": "order-2026-0001", "paymentType": "creditcard", "customer": { "name": "John Smith" }, "cart": [ { "name": "Monthly plan", "quantity": 1, "sku": "PLAN-01", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "JOAO DA SILVA", "expiration": "12/2030", "cvv": "123" } } }' ``` 在生产环境中,请将基础 URL 换成 `https://api.payzu.io/v1`。 金额字段(`amount`、`unitPrice`)始终以**分**为单位。`10000` 相当于 R$ 100,00。 当 `authenticate: false` 时,买家不会被引导至发卡行进行身份认证。如需认证流程,请参阅 [3D Secure](/docs/cartao/three-d-secure)。 ### 解读响应 [#解读响应] 响应包含收款的 `id`、传入的 `externalId`,以及带有 `status`、`reasonCode` 和 `reasonMessage` 的 `creditCardPayment` 对象。主要状态如下: | 代码 | 状态 | 含义 | | -- | ---------------- | -------------------- | | 1 | Authorized | 已获发卡行授权,可进行请款,但尚未完成。 | | 2 | PaymentConfirmed | 支付已确认并完成。 | | 3 | Denied | 支付被授权方拒绝。 | 如果 `creditCardPayment.status` 返回 `2`(PaymentConfirmed),您的第一笔收款已确认。完整的代码列表见[交易状态](/docs/cartao/transaction-status)。 ### 测试场景并配置 webhooks [#测试场景并配置-webhooks] 要在 sandbox 中模拟批准、拒绝和超时,请使用[测试卡](/docs/cartao/test-cards):卡号的末位数字决定交易结果。 要在无需轮询 API 的情况下接收收款状态通知,请在创建收款时传入 `postbackUrl`。payload 结构与校验方法见 [Webhooks](/docs/cartao/webhooks)。 ## 下一步 [#下一步] # Credit Card (/docs/cartao/index.en) The Credit Card API is the API you use to charge cards in your e-commerce, app or platform. A single integration covers the whole charge lifecycle: real-time authorization and capture, installments, 3D Secure authentication, risk analysis with Cybersource, recurring charges and refunds. ## Where to start [#where-to-start] ## Environments [#environments] | Environment | Base URL | | -------------- | --------------------------------- | | **Production** | `https://api.payzu.io/v1` | | **Sandbox** | `https://api.sandbox.payzu.io/v1` | Authentication combines **mTLS (Mutual TLS)** with a **Bearer token**: the client certificate provided by PayZu accompanies every call and the token is obtained via [`POST /token`](/docs/cartao/endpoints/token/post_token). This mechanism guarantees client identity and communication security. See the step by step in [Authentication](/docs/cartao/authentication). All monetary values in the API (`amount`, `unitPrice`) are expressed in **cents**. ## Other PayZu products [#other-payzu-products] ## Support [#support] Ran into a problem or have an integration question? Write to [integracao@payzu.com.br](mailto:integracao@payzu.com.br). # Cartão de Crédito (/docs/cartao) A API de Cartão de Crédito é a API que você usa para cobrar com cartão no seu e-commerce, aplicativo ou plataforma. Uma única integração cobre o ciclo inteiro da cobrança: autorização e captura em tempo real, parcelamento, autenticação 3D Secure, análise de risco com Cybersource, recorrência e estorno. ## Por onde começar [#por-onde-começar] ## Ambientes [#ambientes] | Ambiente | Base URL | | ------------ | --------------------------------- | | **Produção** | `https://api.payzu.io/v1` | | **Sandbox** | `https://api.sandbox.payzu.io/v1` | A autenticação combina **mTLS (Mutual TLS)** com um **token Bearer**: o certificado de cliente fornecido pela PayZu acompanha todas as chamadas e o token é obtido em [`POST /token`](/docs/cartao/endpoints/token/post_token). Esse mecanismo garante a identidade do cliente e a segurança da comunicação. Veja o passo a passo em [Autenticação](/docs/cartao/authentication). Todos os valores monetários da API (`amount`, `unitPrice`) são expressos em **centavos**. ## Outros produtos PayZu [#outros-produtos-payzu] ## Suporte [#suporte] Encontrou um problema ou ficou com dúvida na integração? Escreva para [integracao@payzu.com.br](mailto:integracao@payzu.com.br). # 信用卡 (/docs/cartao/index.zh) 信用卡 API 用于在您的电商、应用或平台中发起信用卡收款。一次集成即可覆盖收款的完整生命周期：实时授权与请款、分期、3D Secure 认证、Cybersource 风险分析、循环扣款和退款。 ## 从哪里开始 [#从哪里开始] ## 环境 [#环境] | 环境 | 基础 URL | | ----------- | --------------------------------- | | **生产环境** | `https://api.payzu.io/v1` | | **Sandbox** | `https://api.sandbox.payzu.io/v1` | 身份认证将 **mTLS(Mutual TLS)** 与 **Bearer token** 结合使用:PayZu 提供的客户端证书需随所有调用一起发送,token 通过 [`POST /token`](/docs/cartao/endpoints/token/post_token) 获取。该机制可确保客户端身份与通信安全。详细步骤见[身份认证](/docs/cartao/authentication)。 API 中所有金额字段(`amount`、`unitPrice`)均以**分**为单位。 ## PayZu 其他产品 [#payzu-其他产品] ## 支持 [#支持] 集成中遇到问题或有疑问？请发邮件至 [integracao@payzu.com.br](mailto:integracao@payzu.com.br)。 # International Charges (/docs/cartao/international.en) To create an international charge, set the `currency` field inside `creditCardPayment` to a value other than `BRL` (the default value). To see the possible values, check the list of [currencies](/docs/cartao/currencies). ## Rules for international charges [#rules-for-international-charges] When you change the `currency` field, you also change the currency of the value passed in `amount`. For example, if `currency` is `USD` (US Dollar), the value in `amount` is now expressed in US cents, no longer in Brazilian centavos. * In international charges, the `fraudAnalysis` field becomes **mandatory**. See [Fraud analysis](/docs/cartao/antifraud). * Inside `customer`, only the `name` field is required. * Only foreign cards are accepted. * International charges cannot be paid in installments: always pass `1` in `installments`. * The `amount` is interpreted in the smallest unit of the currency chosen in `currency`. # Cobranças Internacionais (/docs/cartao/international) Para criar uma cobrança internacional, defina o campo `currency` dentro de `creditCardPayment` com um valor diferente de `BRL` (valor padrão). Para consultar os valores possíveis, acesse a lista de [currencies](/docs/cartao/currencies). ## Regras da cobrança internacional [#regras-da-cobrança-internacional] Ao modificar o campo `currency`, você também modifica a moeda do valor passado em `amount`. Por exemplo, se `currency` for `USD` (Dólar Americano), o valor em `amount` passa a ser representado em cents americanos, e não mais em centavos brasileiros. * Em cobranças internacionais, o campo `fraudAnalysis` se torna **obrigatório**. Veja [Antifraude](/docs/cartao/antifraud). * Dentro de `customer`, apenas o campo `name` é obrigatório. * Apenas cartões estrangeiros são aceitos. * Não é possível parcelar cobranças internacionais: passe sempre o valor `1` em `installments`. * O `amount` é interpretado na menor unidade da moeda escolhida em `currency`. # 跨境收款 (/docs/cartao/international.zh) 要创建跨境收款,请将 `creditCardPayment` 中的 `currency` 字段设置为 `BRL`(默认值)以外的值。可用取值请查阅 [currencies](/docs/cartao/currencies) 列表。 ## 跨境收款规则 [#跨境收款规则] 修改 `currency` 字段的同时,也改变了 `amount` 所传金额使用的币种。例如,`currency` 为 `USD`(美元)时,`amount` 表示的是美分,而不再是巴西分。 * 在跨境收款中,`fraudAnalysis` 字段变为**必填**。参见[反欺诈](/docs/cartao/antifraud)。 * `customer` 中只有 `name` 字段是必填的。 * 仅接受境外发行的卡。 * 跨境收款不支持分期:`installments` 必须始终传 `1`。 * `amount` 按 `currency` 所选币种的最小单位解释。 # MDD table (/docs/cartao/mdds.en) The risk strategy is customized to the needs of your business, taking into account the relevance level of the **Merchant Defined Data (MDD)** fields, sent in the `definedFields` array of the `fraudAnalysis` object. See [Antifraud](/docs/cartao/antifraud) for the complete request format. If you do not have one of the data points to send, skip the corresponding MDD. Do not send empty fields. Relevance level of the fields: 1. Relevant 2. Very Relevant 3. Extremely Relevant ## MDD table [#mdd-table] | id | value | Relevance level | Required? | | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :-------- | | 1 | Customer performing the login. Possible values: `"{customer_login}"` (if the end customer logs in to the site to buy) / `"Guest"` (if the end customer buys as a guest). Note: do not send the field if a third party (e.g. an agent) makes the sale directly. | 2 | Yes | | 2 | Number of days the person has been a customer of the store. E.g.: 314. | 3 | No | | 3 | Number of installments of the order. | 3 | No | | 4 | Sales channel. Possible values: `"Call Center"` (purchase by phone) / `"Web"` (purchase on the web) / `"Portal"` (purchase through an agent) / `"Quiosque"` (purchase at a kiosk) / `"Móvel"` (purchase on a phone or tablet). | 3 | Yes | | 5 | Coupon/discount code if the customer uses one in the purchase. | 1 | No | | 6 | Number of days since the customer's last purchase. E.g.: 55. | 3 | No | | 9 | Identifies whether the customer will pick up the product in the store. Possible values: `"SIM"` / `"NAO"`. | 3 | Yes | | 21 | Shipping cost. E.g.: 1085 = R$ 10.85. | 1 | No | | 24 | Number of days since the customer's first purchase. E.g.: 150. | 3 | No | | 25 | Customer's gender. Possible values: `"F"` (female) / `"M"` (male). | 2 | No | | 32 | Identifies whether the email was pasted or typed. Possible values: `"Digitado"` (typed) / `"Colado"` (pasted). | 3 | No | | 33 | Identifies whether the credit card number was pasted or typed. Possible values: `"Digitado"` (typed) / `"Colado"` (pasted). | 3 | No | | 42 | Customer's age. | 2 | No | | 44 | Historical number of purchases made by the customer. | 3 | No | | 45 | Identifies whether it is a purchase made by an employee. Possible values: `"SIM"` / `"NAO"`. | 2 | No | | 83 | Business segment. E.g.: Retail. | 2 | Yes | # Tabela de MDDs (/docs/cartao/mdds) A estratégia de risco é personalizada conforme as necessidades do seu negócio, levando em conta o grau de relevância dos campos **Merchant Defined Data (MDD)**, enviados no array `definedFields` do objeto `fraudAnalysis`. Consulte [Antifraude](/docs/cartao/antifraud) para o formato completo da requisição. Caso não tenha algum dos dados para enviar, ignore o MDD correspondente. Não faça o envio de campos vazios. Nível de relevância dos campos: 1. Relevante 2. Muito Relevante 3. Extremamente Relevante ## Tabela de MDDs [#tabela-de-mdds] | id | value | Nível de Relevância | Obrigatório? | | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ | :----------- | | 1 | Cliente que efetua o login. Possíveis valores: `"{login_do_cliente}"` (caso o cliente final efetue login no site para comprar) / `"Guest"` (caso o cliente final faça a compra como visitante). Obs.: Não enviar o campo caso um terceiro (ex.: um agente) realize a venda diretamente. | 2 | Sim | | 2 | Quantidade de dias que a pessoa é cliente da loja. Ex.: 314. | 3 | Não | | 3 | Quantidade de parcelas do pedido. | 3 | Não | | 4 | Canal de venda. Possíveis valores: `"Call Center"` (compra pelo telefone) / `"Web"` (compra pela web) / `"Portal"` (compra através de agente) / `"Quiosque"` (compra em quiosque) / `"Móvel"` (compra por celular ou tablet). | 3 | Sim | | 5 | Código do cupom/desconto caso o cliente utilize na compra. | 1 | Não | | 6 | Quantidade em dias desde a última compra realizada pelo cliente. Ex.: 55. | 3 | Não | | 9 | Identifica se cliente irá retirar o produto na loja. Possíveis valores: `"SIM"` / `"NAO"`. | 3 | Sim | | 21 | Valor do frete. Ex.: 1085 = R$ 10,85. | 1 | Não | | 24 | Quantidade de dias desde a primeira compra realizada pelo cliente. Ex.: 150. | 3 | Não | | 25 | Sexo do cliente. Possíveis valores: `"F"` (feminino) / `"M"` (masculino). | 2 | Não | | 32 | Identifica se o e-mail foi colado ou digitado. Possíveis valores: `"Digitado"` / `"Colado"`. | 3 | Não | | 33 | Identifica se o número do cartão de crédito foi colado ou digitado. Possíveis valores: `"Digitado"` / `"Colado"`. | 3 | Não | | 42 | Idade do cliente. | 2 | Não | | 44 | Quantidade histórica de compras realizadas pelo cliente. | 3 | Não | | 45 | Identifica se é uma compra realizada por funcionário. Possíveis valores: `"SIM"` / `"NAO"`. | 2 | Não | | 83 | Segmento de negócio. Ex.: Varejo. | 2 | Sim | # MDD 字段表 (/docs/cartao/mdds.zh) 风控策略会根据您业务的需求定制,并参考 **Merchant Defined Data (MDD)** 字段的相关性程度,这些字段通过 `fraudAnalysis` 对象的 `definedFields` 数组发送。完整的请求格式请参阅[反欺诈](/docs/cartao/antifraud)。 如果缺少某项数据,请直接省略对应的 MDD,不要发送空字段。 字段的相关性级别: 1. 相关 2. 非常相关 3. 极其相关 ## MDD 字段表 [#mdd-字段表] | id | value | 相关性级别 | 是否必填 | | -- | ------------------------------------------------------------------------------------------------------------- | :---- | :--- | | 1 | 登录的客户。可能取值:`"{customer_login}"`(最终客户在网站登录后购买时)/ `"Guest"`(最终客户以访客身份购买时)。注:如果由第三方(例如代理)直接完成销售,请勿发送该字段。 | 2 | 是 | | 2 | 该用户成为店铺客户的天数。例:314。 | 3 | 否 | | 3 | 订单的分期数。 | 3 | 否 | | 4 | 销售渠道。可能取值:`"Call Center"`(电话购买)/ `"Web"`(网页购买)/ `"Portal"`(通过代理购买)/ `"Quiosque"`(自助终端购买)/ `"Móvel"`(手机或平板购买)。 | 3 | 是 | | 5 | 客户在购买时使用的优惠券/折扣码。 | 1 | 否 | | 6 | 距客户上一次购买的天数。例:55。 | 3 | 否 | | 9 | 标识客户是否到店自提商品。可能取值:`"SIM"` / `"NAO"`。 | 3 | 是 | | 21 | 运费金额。例:1085 = R$ 10,85。 | 1 | 否 | | 24 | 距客户首次购买的天数。例:150。 | 3 | 否 | | 25 | 客户性别。可能取值:`"F"`(女)/ `"M"`(男)。 | 2 | 否 | | 32 | 标识电子邮箱是粘贴还是键入的。可能取值:`"Digitado"`(键入)/ `"Colado"`(粘贴)。 | 3 | 否 | | 33 | 标识信用卡卡号是粘贴还是键入的。可能取值:`"Digitado"`(键入)/ `"Colado"`(粘贴)。 | 3 | 否 | | 42 | 客户年龄。 | 2 | 否 | | 44 | 客户的历史购买次数。 | 3 | 否 | | 45 | 标识是否为员工购买。可能取值:`"SIM"` / `"NAO"`。 | 2 | 否 | | 83 | 业务领域。例:Varejo(零售)。 | 2 | 是 | # Recurring Payments (/docs/cartao/recurrence.en) A recurrence is a subscription: you create the first charge specifying the interval and, from then on, each cycle is charged automatically to the customer's card, with no new API call. * **First charge**: created immediately, in the response of [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). * **Following cycles**: generated automatically at the configured interval (monthly or annual). * Each cycle becomes a charge linked to the recurrence, numbered by `recurrenceCycle` (`0` = initial, `1..n` = cycles). * On every cycle you receive a [`recurrence.cycle`](/docs/cartao/webhooks) postback at your `postbackUrl`. Recurring payments may not be available for all accounts. Check with support about availability on your account. ## Create a recurrence [#create-a-recurrence] A recurrence starts from a regular credit card charge ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)) with the `recurrence` node added. `recurrence` fields in the request: | Field | Type | Description | | ---------- | ---------------- | ------------------------------------------------------------------------------ | | `interval` | string, required | `Monthly` or `Annual` | | `endDate` | string, optional | End date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely. | A recurrence is always a single payment. The `installments` field must be `1`; higher values are rejected. Example request (amounts in cents): ```json { "amount": 10000, "paymentType": "creditcard", "externalId": "assinatura-123", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF" }, "cart": [{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } }, "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" } } ``` Response: ```json { "id": "uuid-da-cobranca", "amount": 10000, "creditCardPayment": { "status": 2, "reference": "PaymentId" }, "recurrence": { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "endDate": "2027-06-12T00:00:00.000Z", "nextRecurrency": "2026-07-12T00:00:00.000Z" }, "recurrenceCycle": 0 } ``` `recurrence` fields in the response: | Field | Description | | -------------------- | --------------------------------------------------------------------------- | | `recurrentPaymentId` | Identifier of the recurrence. Use it in the query and management endpoints. | | `status` | `ACTIVE`, `INACTIVE` or `ENDED`. | | `amount` | Amount of each cycle, in cents. | | `nextRecurrency` | Date of the next automatic charge. | | `endDate` | End date, if provided at creation. | ## How cycles work [#how-cycles-work] You don't need to do anything for the cycles to happen. At each interval, PayZu charges the card and creates a new charge linked to the recurrence, with `recurrenceCycle` incremented. For every charged cycle, a postback with the `recurrence.cycle` event is sent to your `postbackUrl`. Use it to reconcile the charges. ## Lifecycle [#lifecycle] | Status | Meaning | | ---------- | --------------------------------------------------------------------- | | `ACTIVE` | Active, generating cycles at the configured interval. | | `INACTIVE` | Deactivated (manually or by the issuer). No new cycles are generated. | | `ENDED` | Ended after reaching the `endDate`. | ## Manage the recurrence [#manage-the-recurrence] Use the `recurrentPaymentId` returned at creation to query and manage the subscription: ### Get a recurrence [#get-a-recurrence] `GET /charges/recurrences/{recurrentPaymentId}` returns the current state of the recurrence: ```json { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } ``` ### List the recurrence charges [#list-the-recurrence-charges] Use [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) with the `recurrentPaymentId` filter: ``` GET /charges?recurrentPaymentId={recurrentPaymentId} ``` Lists the initial charge and every cycle generated so far (paginated). It also accepts the `limit`, `page`, `startDate` and `endDate` filters. ### Update the amount [#update-the-amount] `PUT /charges/recurrences/{recurrentPaymentId}/amount` changes the amount of upcoming charges. It does not affect cycles already generated. ```json { "amount": 12000 } ``` ### Deactivate and reactivate [#deactivate-and-reactivate] * `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` stops the recurrence: no new cycle is generated and the status becomes `INACTIVE`. * `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` resumes a deactivated recurrence: the status goes back to `ACTIVE`. # Pagamentos Recorrentes (/docs/cartao/recurrence) Uma recorrência é uma assinatura: você cria a primeira cobrança informando o intervalo e, a partir daí, cada ciclo é cobrado automaticamente no cartão do cliente, sem nova chamada à API. * **Primeira cobrança**: criada na hora, na resposta do [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). * **Ciclos seguintes**: gerados automaticamente no intervalo configurado (mensal ou anual). * Cada ciclo vira uma cobrança vinculada à recorrência, numerada por `recurrenceCycle` (`0` = inicial, `1..n` = ciclos). * A cada ciclo você recebe um postback [`recurrence.cycle`](/docs/cartao/webhooks) na sua `postbackUrl`. Pagamentos recorrentes podem não estar disponíveis para todas as contas. Consulte o suporte sobre a disponibilidade na sua conta. ## Criar uma recorrência [#criar-uma-recorrência] Uma recorrência nasce de uma cobrança de cartão de crédito comum ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)) com o nó `recurrence` adicionado. Campos de `recurrence` no request: | Campo | Tipo | Descrição | | ---------- | ------------------- | --------------------------------------------------------------------------------- | | `interval` | string, obrigatório | `Monthly` (mensal) ou `Annual` (anual) | | `endDate` | string, opcional | Data final no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente. | Recorrência é sempre à vista. O campo `installments` precisa ser `1`; valores maiores são rejeitados. Request de exemplo (valores em centavos): ```json { "amount": 10000, "paymentType": "creditcard", "externalId": "assinatura-123", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF" }, "cart": [{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } }, "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" } } ``` Resposta: ```json { "id": "uuid-da-cobranca", "amount": 10000, "creditCardPayment": { "status": 2, "reference": "PaymentId" }, "recurrence": { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "endDate": "2027-06-12T00:00:00.000Z", "nextRecurrency": "2026-07-12T00:00:00.000Z" }, "recurrenceCycle": 0 } ``` Campos de `recurrence` na resposta: | Campo | Descrição | | -------------------- | --------------------------------------------------------------------- | | `recurrentPaymentId` | Identificador da recorrência. Use nos endpoints de consulta e gestão. | | `status` | `ACTIVE`, `INACTIVE` ou `ENDED`. | | `amount` | Valor de cada ciclo, em centavos. | | `nextRecurrency` | Data da próxima cobrança automática. | | `endDate` | Data final, se informada na criação. | ## Como funcionam os ciclos [#como-funcionam-os-ciclos] Você não precisa fazer nada para os ciclos acontecerem. A cada intervalo, a PayZu cobra o cartão e cria uma nova cobrança vinculada à recorrência, com o `recurrenceCycle` incrementado. A cada ciclo cobrado, um postback com o evento `recurrence.cycle` é enviado para a sua `postbackUrl`. Use-o para conciliar as cobranças. ## Ciclo de vida [#ciclo-de-vida] | Status | Significado | | ---------- | ---------------------------------------------------------------- | | `ACTIVE` | Ativa, gerando os ciclos no intervalo configurado. | | `INACTIVE` | Desativada (manualmente ou pelo emissor). Não gera novos ciclos. | | `ENDED` | Encerrada por ter atingido a `endDate`. | ## Gerenciar a recorrência [#gerenciar-a-recorrência] Use o `recurrentPaymentId` retornado na criação para consultar e gerenciar a assinatura: ### Consultar uma recorrência [#consultar-uma-recorrência] `GET /charges/recurrences/{recurrentPaymentId}` retorna o estado atual da recorrência: ```json { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } ``` ### Listar as cobranças da recorrência [#listar-as-cobranças-da-recorrência] Use [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) com o filtro `recurrentPaymentId`: ``` GET /charges?recurrentPaymentId={recurrentPaymentId} ``` Lista a cobrança inicial e todos os ciclos já gerados (paginado). Aceita também os filtros `limit`, `page`, `startDate` e `endDate`. ### Alterar o valor [#alterar-o-valor] `PUT /charges/recurrences/{recurrentPaymentId}/amount` altera o valor das próximas cobranças. Não afeta ciclos já gerados. ```json { "amount": 12000 } ``` ### Desativar e reativar [#desativar-e-reativar] * `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` interrompe a recorrência: nenhum ciclo novo é gerado e o status vira `INACTIVE`. * `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` retoma uma recorrência desativada: o status volta para `ACTIVE`. # 循环扣款 (/docs/cartao/recurrence.zh) 循环扣款就是一笔订阅:您在创建首笔收款时指定扣款周期,此后每个周期都会自动从客户的信用卡扣款,无需再次调用 API。 * **首笔收款**:即时创建,直接在 [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) 的响应中返回。 * **后续周期**:按配置的周期(每月或每年)自动生成。 * 每个周期都会生成一笔关联到该循环扣款的收款,并以 `recurrenceCycle` 编号(`0` 为首笔,`1..n` 为后续周期)。 * 每个周期您都会在 `postbackUrl` 收到一个 [`recurrence.cycle`](/docs/cartao/webhooks) postback。 循环扣款可能并非对所有账户开放。请咨询支持了解您账户的可用性。 ## 创建循环扣款 [#创建循环扣款] 循环扣款由一笔普通的信用卡收款([`POST /charges`](/docs/cartao/endpoints/charges/post_charges))加上 `recurrence` 节点创建。 Request 中 `recurrence` 的字段: | 字段 | 类型 | 说明 | | ---------- | --------- | ----------------------------------- | | `interval` | string,必填 | `Monthly`(每月)或 `Annual`(每年) | | `endDate` | string,可选 | 结束日期,格式 `YYYY-MM-DD`。不填时循环扣款将无限期持续。 | 循环扣款始终为一次性全额付款。`installments` 字段必须为 `1`,更大的值会被拒绝。 Request 示例(金额以分为单位): ```json { "amount": 10000, "paymentType": "creditcard", "externalId": "assinatura-123", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF" }, "cart": [{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } }, "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" } } ``` 响应: ```json { "id": "uuid-da-cobranca", "amount": 10000, "creditCardPayment": { "status": 2, "reference": "PaymentId" }, "recurrence": { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "endDate": "2027-06-12T00:00:00.000Z", "nextRecurrency": "2026-07-12T00:00:00.000Z" }, "recurrenceCycle": 0 } ``` 响应中 `recurrence` 的字段: | 字段 | 说明 | | -------------------- | ------------------------------ | | `recurrentPaymentId` | 循环扣款的标识符。用于各查询和管理 endpoint。 | | `status` | `ACTIVE`、`INACTIVE` 或 `ENDED`。 | | `amount` | 每个周期的金额,以分为单位。 | | `nextRecurrency` | 下一次自动扣款的日期。 | | `endDate` | 结束日期(若创建时提供)。 | ## 周期如何运作 [#周期如何运作] 周期的执行不需要您做任何操作。每到一个周期,PayZu 会自动扣款并创建一笔关联到该循环扣款的新收款,`recurrenceCycle` 随之递增。每完成一个周期的扣款,PayZu 都会向您的 `postbackUrl` 发送 `recurrence.cycle` 事件的 postback,可用它进行对账。 ## 生命周期 [#生命周期] | 状态 | 含义 | | ---------- | ----------------------- | | `ACTIVE` | 生效中,按配置的周期持续生成扣款。 | | `INACTIVE` | 已停用(手动或由发卡行停用)。不再生成新周期。 | | `ENDED` | 已因达到 `endDate` 而结束。 | ## 管理循环扣款 [#管理循环扣款] 使用创建时返回的 `recurrentPaymentId` 查询和管理订阅: ### 查询循环扣款 [#查询循环扣款] `GET /charges/recurrences/{recurrentPaymentId}` 返回循环扣款的当前状态: ```json { "recurrentPaymentId": "uuid-da-recorrencia", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } ``` ### 列出循环扣款下的收款 [#列出循环扣款下的收款] 使用 [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) 并携带 `recurrentPaymentId` 过滤条件: ``` GET /charges?recurrentPaymentId={recurrentPaymentId} ``` 返回首笔收款以及已生成的全部周期(分页)。同时支持 `limit`、`page`、`startDate` 和 `endDate` 过滤参数。 ### 修改金额 [#修改金额] `PUT /charges/recurrences/{recurrentPaymentId}/amount` 修改后续扣款的金额。不影响已生成的周期。 ```json { "amount": 12000 } ``` ### 停用与重新启用 [#停用与重新启用] * `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` 中止循环扣款:不再生成新周期,状态变为 `INACTIVE`。 * `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` 恢复已停用的循环扣款:状态回到 `ACTIVE`。 # Reference codes (/docs/cartao/reference-codes.en) Use the exact values from these tables when building your requests and when interpreting the API responses. ## Card brands (Brand) [#card-brands-brand] Accepted values for the card brand: | Brand | Value | | -------------------------------- | ----------- | | | `Visa` | | | `Master` | | | `Elo` | | Diners Club | `Diners` | | | `Hipercard` | ## Currencies [#currencies] The full list of accepted currencies (ISO 4217) is on a dedicated page. ## Payment types [#payment-types] Supported payment types: | Type | Description | | ------------ | ----------- | | `creditcard` | Credit card | # Códigos de referência (/docs/cartao/reference-codes) Use os valores exatos destas tabelas ao montar suas requisições e ao interpretar as respostas da API. ## Bandeiras (Brand) [#bandeiras-brand] Valores aceitos para a bandeira do cartão: | Bandeira | Valor | | -------------------------------- | ----------- | | | `Visa` | | | `Master` | | | `Elo` | | Diners Club | `Diners` | | | `Hipercard` | ## Moedas (Currencies) [#moedas-currencies] A lista completa de moedas aceitas (padrão ISO 4217) está em uma página dedicada. ## Tipos de pagamento [#tipos-de-pagamento] Tipos de pagamento suportados: | Tipo | Descrição | | ------------ | ----------------- | | `creditcard` | Cartão de crédito | # 参考代码 (/docs/cartao/reference-codes.zh) 在构建请求和解析 API 响应时,请使用下列表格中的准确值。 ## 卡组织(Brand) [#卡组织brand] 信用卡卡组织的可选值: | 卡组织 | 值 | | -------------------------------- | ----------- | | | `Visa` | | | `Master` | | | `Elo` | | Diners Club | `Diners` | | | `Hipercard` | ## 货币(Currencies) [#货币currencies] 完整的受支持货币列表(遵循 ISO 4217)位于独立页面。 ## 支付类型 [#支付类型] 支持的支付类型: | 类型 | 描述 | | ------------ | --- | | `creditcard` | 信用卡 | # Card network retry program (/docs/cartao/retry-program.en) ## What are retries? [#what-are-retries] When a customer tries to make a card purchase in your store, the transaction may be declined for several reasons. Subsequent attempts to complete the transaction with the same card are called retries. Card purchase transactions (card present or card not present) and Zero Auth transactions (card validation) are subject to the card networks' retry rules. ### Fees and limits by network [#fees-and-limits-by-network] Each card network sets specific fees for retries, and the number of attempts allowed before fees apply also varies by network. ### Card present and card not present [#card-present-and-card-not-present] The networks define distinct rules for card present and card not present transactions, such as online sales. ### Penalties for exceeding the limits [#penalties-for-exceeding-the-limits] E-commerce merchants that do not follow the retry rules may be penalized with additional fees for exceeded transactions, according to each network's program. ## Reversible and irreversible declines [#reversible-and-irreversible-declines] Aiming to improve the purchase experience, the payments industry, in partnership with ABECS, standardized the response codes for declined card transactions. Retry attempts were classified into two types, irreversible and reversible. **Irreversible: never retry** This type of decline indicates that the card is canceled, was lost or stolen, there is confirmed fraud, or the transaction is not allowed for the specific product. In any of these situations, the issuer will never grant an approval. If an authorization attempt occurs after an irreversible decline, without changing any data in the request, the transaction will continue to be declined. **Reversible: retry allowed** In this case, the issuer may eventually approve the transaction, but does not do so at that moment due to temporary problems such as a system failure, insufficient available limit, suspected fraud, or an excessive number of incorrect PIN entry attempts. These declines are temporary and may change over time, allowing approval on a new attempt. Visa, Mastercard and Elo adjusted their rules to limit the number of authorization attempts on declined transactions. These changes establish fees when the number of attempts exceeds the allowed limit. See below the specific rules for each network. ## Mastercard [#mastercard] Mastercard has the Transaction Processing Excellence (TPE) program, which covers two categories: 1. Excessive Attempts: monitors retries of declined transactions in card present and card not present environments. Valid for both reversible and irreversible decline codes. 2. Merchant Advice Code Transaction Excellence (MAC): monitors retries of declined transactions in card not present environments that are irreversible. Fees apply only to MAC 03 and 21. ### Excessive Attempts [#excessive-attempts] These are charges applied when the merchant exceeds the transaction retry rules. The network also monitors any nominal-amount authorization, approved, with a subsequent refund, for transactions below 1 whole currency unit or the equivalent of US$ 1. Monitoring applies to retries of declined and approved purchase transactions, made in card present and card not present environments. Excessive Attempts table: | Categories | Codes | Effective period | Domestic fee | International fee | When it occurs | Retry allowed | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------ | ----------------- | -------------------------- | ------------------------ | | Card present and card not present | Any decline code not assigned to MAC 03 and 21. Also the MAC codes if the "Excessive Attempts" limits are not respected | Until 31/01/2023 | R$ 2.00 | \* | From the 11th retry onward | Retry allowed after 24h. | | Card present and card not present | Any decline code not assigned to MAC 03 and 21. Also the MAC codes if the "Excessive Attempts" limits are not respected | In effect since 01/02/2023 | R$ 2.00 | \* | From the 8th retry onward | Retry allowed after 24h. | * All payment transactions on the same card and same merchant number are considered retries; * Mastercard postponed the effective date of the new Excessive Attempts program rules to 01/02/2023, previously scheduled to start on 01/11/2022. Here are the changes: 1. The excess considered in the program will start from the eighth retry within the assessment month; the amounts charged were changed. 2. Mastercard is also introducing a limit of 35 declined attempts on the same card and same merchant number over a continuous 30-day period. Even if the store does not exceed the limit of seven retries within 24h, but exceeds the monthly limit, the fee will be applied. The current Excessive Attempts program rule has been in effect since 01/02/2023 (Excessive Attempts table): the fee applies from the 8th retry of the same transaction (same card and same merchant number), and retrying is allowed after 24 hours. Until 31/01/2023 the previous rule applied, allowing 10 attempts before the fee. ### Merchant Advice Code Transaction Excellence (MAC) [#merchant-advice-code-transaction-excellence-mac] These are charges applied when the merchant retries an authorization request for irreversible response codes with the same card, valid for card not present. Within this retry program, there are programs specifically targeted at the "Do not retry this transaction" scenario. For those cases, Mastercard identifies the transactions with the values MAC 03 and MAC 21, for example. The MAC program includes several values, but only MAC 03 and 21 carry a specific fee. The other MACs do not fall under this fee. The other MAC codes (01, 02, 04, 24, 25, 26, 27, 28, 29, 30, 40 and 41) are not part of the MAC fee program, but they do count toward the Excessive Attempts program fee if the limits are exceeded. Since 14/10/2022 Mastercard introduced new MAC codes (24, 25, 26, 27, 28, 29 and 30) when an issuer declines a transaction with response code 51 (insufficient funds) followed by one of the MACs in the table below, so the merchant can take the best action. Table with the full list of MACs: | MAC | Description | Note | | --- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | New account information available (ABU) | The account data used in the transaction needs to be updated, using ABU, for example. | | 02 | Cannot approve at this time, try later | Retry the transaction after 72 hours or try the transaction with a different payment method. | | 03 | Retry not allowed | Find another way to secure the payment, avoiding unnecessary costs from multiple authorization requests that will continue to result in declines. | | 04 | Token requirements not met for this token model | The token requirements need to be reviewed, as they were not met for the token model sent in the transaction. | | 21 | Plan canceled | The buyer cancels a plan and, even after the cancellation, the merchant keeps sending purchase authorization requests. | | 24 | Retry after 1 hour | Valid only for response code 51 (insufficient funds). | | 25 | Retry after 24 hours | Valid only for response code 51 (insufficient funds). | | 26 | Retry after 2 days | Valid only for response code 51 (insufficient funds). | | 27 | Retry after 4 days | Valid only for response code 51 (insufficient funds). | | 28 | Retry after 6 days | Valid only for response code 51 (insufficient funds). | | 29 | Retry after 8 days | Valid only for response code 51 (insufficient funds). | | 30 | Retry after 10 days | Valid only for response code 51 (insufficient funds). | | 40 | Retry not allowed | Non-reloadable prepaid card for consumption. | | 41 | Retry not allowed | Consumer single-use virtual card. | In addition, some return codes will no longer be sent: * 04 (Capture card) * 14 (Invalid card number) * 43 (Stolen card) * 54 (Expired card) * 57 (Transaction not permitted) * 62 (Restricted card) * 63 (Security violation) **Mastercard return categorization** Mastercard may consolidate some issuer response codes, which often do not tell the merchant whether a retry is allowed, into three Mastercard-exclusive codes: * 79 (Lifecycle); * 82 (Policy); * 83 (Fraud/Security). The original codes will be replaced by the Merchant Advice Code (MAC), which will accompany codes 79, 82 and 83 to determine whether the transaction can be retried. For example: | When | Then | And the response code | | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- | | The issuer declines the transaction using response code 54 (Expired card) | Mastercard will replace code 54 with code 79 (lifecycle decline) | Accompanied by the corresponding Merchant Advice Code (MAC) | **MAC 03 and MAC 21 retry program** Assessment method: * Card not present transactions are considered; * All payment transactions on the same card and same merchant number are considered retries; * Retries in the MAC program with values MAC 03 and MAC 21 are counted; * Valid for any response code; * The excess counted in the program starts from the 1st retry within the assessment month; * The counter resets after the 30-day period; * Retries can be charged under MAC 03/21 and under Excessive Attempts if the limit of each program is exceeded; * The fee was R$ 1.25 and, starting January 1, 2023, the amount listed below took effect. Fee table: | Retry number | Rule | | ------------------------- | --------------------------------------------------------------------------- | | From the 1st retry onward | R$ 2.50 (two reais and fifty cents) per retry, starting from the 1st retry. | ## Visa [#visa] The retry program established by Visa generates charges when the merchant exceeds the retry rules. The goal is to create balance in the transaction ecosystem to ensure that acquirers and merchants provide accurate information about retries and reduce unnecessary new attempts. The network requires issuers to use correct, non-generic response codes to make it easier to identify the reason a transaction was declined. Visa splits these codes into reversible and irreversible, valid for both card present and card not present transactions: * Reversible codes: up to 20 attempts to approve the same transaction are allowed (with the same card, transaction, expiration date, amount and merchant) within a 30-day period. After 30 days, counted from the first attempt, any retry will be charged. Once the 30-day period has passed, if a retry of the same transaction is sent, the fee will already be applied. Thus, the 20-attempt rule no longer applies and the 30 consecutive-day period takes effect. * Irreversible codes: only the 1st attempt to approve the transaction is allowed (with the same card, transaction, expiration date, amount and merchant). On the second attempt, the transaction will already be charged, regardless of when it occurs. Fees: when the attempt limits set by the network are exceeded, a fee is charged for each exceeding transaction. * Domestic: USD 0.10 + 13.83% tax; * Foreign: USD 0.25 + 13.83% tax. Fees have applied since April 2021. Visa grouped the return codes into four categories: * **Category 1: issuer will never approve.** Indicates that the card was canceled or never existed, or that the decline is the result of a permanent restriction or error condition that will prevent a future approval. * **Category 2: issuer cannot approve at this time.** Indicates that the decline is the result of a temporary condition such as credit risk, issuer velocity controls or other card restrictions that may allow a retried transaction to be approved. In some cases, the decline requires an action from the cardholder or issuer to remove the restriction before an approval can be obtained. * **Category 3: data quality.** When a data error is identified by the issuer, the transaction is declined as a consequence. Merchants must revalidate payment data before retrying. Merchants and acquirers must monitor these decline codes due to the potential fraud exposure. Note: category 3 has, in addition to the limits considered in category 2, a different limit that is cumulative. A merchant can perform up to 25,000 transactions in a 30-day period (in this case considering only the merchant number and decline codes). If the limit is exceeded, all transactions declined under category 3 will be charged. * **Category 4: generic response codes.** Category 4 includes all other decline response codes not in categories 1, 2 and 3, since there may be circumstances where no response code value exists for a specific decline condition. Issuers may use other response code values defined in the VisaNet Technical Specifications; however, their use must remain minimal. Issuers must use response codes that most accurately reflect the reason for the declines. That is, focus on categories 1 (the issuer will never approve), 2 (the issuer cannot approve at this time) and 3 (data quality) and avoid using 4 (generic response code). Issuers must limit this category as much as possible. The Category 4 fee is charged to ensure that no more than the regionally approved percentage of the issuer's total declines are categorized as Category 4. Issuers that exceed the regionally defined limit will receive the Generic Response Code Fee on a per-transaction basis for each decline in excess of the defined limit. Table with the rules and decline codes. The rules in the table below are valid for both purchase transactions and Zero Auth transactions: | Category | Type | Codes | Rules | | ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Category 1
Issuer will not approve new attempts | Irreversible | 04 - Pick up card
07 - Pick up card, special conditions
12 - Invalid transaction
14\* - Invalid account number
15 - Issuer does not exist
41 - Pick up card (lost card)
43 - Pick up card (stolen card)
46 - Closed account
57 - Transaction not permitted to cardholder
R0 - Stop payment order
R1 - Revocation of authorization order
R3 - Revocation of all authorization orders | Fee charged from the 2nd attempt onward. | | Category 2
Issuer will not approve at this time; new attempts are allowed | Reversible | 03 - Invalid merchant
19 - Re-enter the transaction
39\*\* - No credit account
51 - Insufficient funds
52\*\* - No checking account
53\*\* - No savings account
59 - Suspected fraud
61 - Exceeds withdrawal amount limits
62 - Restricted card (card invalid in the region or country)
65 - Exceeds withdrawal frequency
75 - Allowed number of PIN entry attempts exceeded
78 - Blocked, first use or special condition (the account is temporarily blocked)
86 - ATM malfunction
91 - Issuer or switch inoperative
93 - The transaction cannot be completed (violation of law)
96 - System malfunction
N3 - Cash withdrawal service unavailable
N4 - Cash request exceeds issuer limit
Z5\*\*\* - Valid account, but amount not supported
5C\*\*\*\* - Transaction not supported/blocked by the issuer
9G\*\*\*\* - Blocked by the cardholder (contact the cardholder). | Fee charged from the 16th attempt onward: the merchant may retry the same transaction 15 times.
From the 16th attempt (with the same card, transaction, expiration date, amount and merchant) within a period of 30 consecutive days from the 1st attempt, the transaction will be charged. Once the 30-day period has passed, Visa does not allow any new attempt. So, if an attempt for that same transaction is sent, the fee will already be applied to that retry (at which point the 15-attempt rule no longer applies and the 30 consecutive-day period takes effect). | | Category 3
Data quality | Reversible | 54 - Expired card
55 - Incorrect PIN
70 - PIN data required (Europe region only)
82 - Negative CAM, dCVV, iCVV or online CVV results
1A - Additional customer authentication required (Europe region only)
6P - Verification failure (cardholder identification does not match issuer records)
N7 - Decline due to CVV2 failure (Visa) | Fee charged from the 16th attempt onward: the merchant may retry the same transaction 15 times.
From the 16th attempt (with the same card, transaction, expiration date, amount and merchant) within a period of 30 consecutive days from the 1st attempt, the transaction will be charged. Once the 30-day period has passed, Visa does not allow any new attempt. So, if an attempt for that same transaction is sent, the fee will already be applied to that retry (at which point the 15-attempt rule no longer applies and the 30 consecutive-day period takes effect). | | Category 4
Generic response codes | Reversible | Generic response codes not listed in categories 1, 2, 3 | Fee charged from the 16th attempt onward: the merchant may retry the same transaction 15 times.
From the 16th attempt (with the same card, transaction, expiration date, amount and merchant) within a period of 30 consecutive days from the 1st attempt, the transaction will be charged. Once the 30-day period has passed, Visa does not allow any new attempt. So, if an attempt for that same transaction is sent, the fee will already be applied to that retry (at which point the 15-attempt rule no longer applies and the 30 consecutive-day period takes effect). | Since April 2023, the allowed total decline count limit for category 3 went from 10,000 to 25,000 declines in a 30-day billing cycle. ## Elo [#elo] The rules presented below took effect in January 2025. The goal of the change is to ensure that merchants and acquirers reduce unnecessary new approval attempts. Transactions are assessed monthly, counted from the 1st to the last calendar day of the violation month. Fee amounts: | Fee | | ------------------------------------------------ | | R$ 0.80 (eighty cents) for each exceeded attempt | ### Charging rules by group [#charging-rules-by-group] The network will consider reversible and irreversible codes according to groups split into three categories. Below are the changes that took effect: | Group | Description | Fee | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Group 1 | Card not present transactions declined with irreversible codes, considering the same card number, same merchant CNPJ and same amount. | The fee applies from the 2nd retry within the assessment month. | | Group 2 | Card not present transactions declined with reversible codes. | The fee applies from the 16th retry within the assessment month. | | Group 3 | Card not present transactions declined with Brute Force Attack characteristics, considering transactions with the same merchant root CNPJ. | Applies from 10,001 declined transactions (within the code category) that exceed 5% of total declines, depending on the payment transaction volume of the CNP involved. | Group classification: | Group 1
Issuer will never approve (IRREVERSIBLE) | Group 2
Issuer cannot approve at this time (REVERSIBLE) | Group 3
Data quality, revalidate information (\*) | | ----------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------ | | 57 - Not allowed | 51 - Insufficient limit | 54 - Expired card | | 14 or 56 - Invalid card (\*) | 59 - Suspected fraud | 55 - Invalid PIN | | 58 - Invalid merchant | 04 - Redo the transaction | 82 - Invalid card cryptogram | | 46 - Closed account | 06 - Contact acquirer | 63 - CVE invalid or not present | | FM - Use the chip | 38 - Purchase PIN attempts exceeded | | | 19 - Contact acquirer | 61 - Withdrawal amount exceeded | | | 12 - Card error | 62 - Temporary delinquency block | | | 30 - Messaging format error | 65 - Withdrawal count exceeded | | | 13 - Invalid transaction amount | 75 - PIN attempts exceeded / withdrawal | | | 23 - Invalid installment amount | 78 - New card not unblocked or blocked by the customer APP/NFC/E-COM | | | 41 - Lost card | 91 - Issuer offline | | | 43 - Stolen card | | | | 64 - Invalid minimum transaction amount | | | | 83 - PIN encryption error | | | | 76 - Invalid destination account | | | | 77 - Invalid source account | | | ## Other networks [#other-networks] * Reversible codes: new retries will be allowed for the same customer and card. There is no pre-established limit or period. Important: before making a new attempt, follow the guidance received in the declined transaction response. * Irreversible codes: no authorizations will be allowed for the same card or merchant after receiving the 1st decline response from the issuer. ## Retry by return code [#retry-by-return-code] The table below maps the codes returned in `returnCode` to their meaning, the recommended action, and whether a retry is allowed. | Response code | Definition | Meaning | Action | Allows retry | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | 0 | Transaction successfully authorized. | Transaction successfully authorized. | Transaction successfully authorized. | No | | 002 | Invalid credentials | There is a block on the terminal at PayZu | Contact PayZu e-commerce support | Yes | | 2 | Transaction not authorized. Referred transaction. | Transaction not authorized. Referred (suspected fraud) by the issuing bank. | Transaction not authorized. Contact your issuing bank. | No | | 9 | Transaction partially canceled successfully. | Transaction partially canceled successfully | Transaction partially canceled successfully | No | | 11 | Transaction successfully authorized for a card issued abroad | Transaction successfully authorized. | Transaction successfully authorized. | No | | 21 | Cancellation not performed. Transaction not found. | Could not process the cancellation. If the error persists, contact PayZu. | Could not process the cancellation. Try again later. If the error persists, contact the online store. | No | | 22 | Invalid installment plan. Invalid number of installments. | Could not process the transaction. Invalid number of installments. If the error persists, contact PayZu. | Could not process the transaction. Invalid amount. Redo the transaction confirming the data provided. If the error persists, contact the online store. | No | | 24 | Invalid number of installments. | Could not process the transaction. Invalid number of installments. If the error persists, contact PayZu. | Could not process the transaction. Invalid number of installments. Redo the transaction confirming the data provided. If the error persists, contact the online store. | No | | 60 | Transaction not authorized. | Transaction not authorized. Try again. If the error persists, the cardholder should contact the issuing bank. | Could not process the transaction. Try again later. If the error persists, contact your issuing bank. | Only 4 times within 16 days. | | 67 | Transaction not authorized. Card blocked for purchases today. | Transaction not authorized. Card blocked for purchases today. The block may have been caused by too many invalid attempts. The card will be automatically unblocked at midnight. | Transaction not authorized. Card temporarily blocked. Contact your issuing bank. | From the next day on, only 4 times within 16 days. | | 70 | Transaction not authorized. Limit exceeded/no balance. | Transaction not authorized. Limit exceeded/no balance. | Transaction not authorized. Contact your issuing bank. | From the next day on, only 4 times within 16 days. | | 72 | Cancellation not performed. Insufficient balance available for the cancellation. | Cancellation not performed. Insufficient balance available for the cancellation. If the error persists, contact PayZu. | Cancellation not performed. Try again later. If the error persists, contact the online store. | No | | 79 | Mastercard transaction not allowed for this card | Transaction not authorized. Cannot process the transaction due to an error related to the cardholder's card. Ask the cardholder to contact the issuing bank. | Contact your bank | No | | 80 | Transaction not authorized. Mismatch in the transaction/payment date. | Transaction not authorized. Invalid transaction date or first payment date. | Transaction not authorized. Redo the transaction confirming the data. | No | | 82 | Mastercard transaction not authorized. Call the issuer | Transaction not authorized due to issuer rules. Advise the cardholder to contact the issuing bank. | Contact your bank | No | | 83 | Mastercard transaction suspected of fraud | Transaction not authorized. Suspected fraud by the issuing bank. | Contact your bank | No | | 85 | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists there may be a problem with the merchant terminal, in which case the merchant should contact PayZu. | Transaction not allowed. Enter the card data again. If the error persists, contact the online store. | No | | 89 | Transaction error. | Transaction not authorized. Transaction error. The cardholder should try again and, if the error persists, contact the issuing bank. | Transaction not authorized. Transaction error. Try again and, if the error persists, contact your issuing bank. | Only 4 times within 16 days. | | 90 | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists there may be a problem with the merchant terminal, in which case the merchant should contact PayZu. | Transaction not allowed. Enter the card data again. If the error persists, contact the online store. | No | | 97 | Amount not allowed for this transaction. | Transaction not authorized. Amount not allowed for this transaction. | Transaction not authorized. Amount not allowed for this transaction. | No | | 98 | System/communication unavailable. | Transaction not authorized. Issuer system out of communication. If it is widespread, check SITEF, GATEWAY and/or connectivity. | Your transaction cannot be processed. Try again later. If the error persists, contact the online store. | Only 4 times within 16 days. | | 475 | Cancellation timeout | The application did not respond within the expected time. | Try again after a few seconds. If it persists, contact Support. | No | | 999 | System/communication unavailable. | Transaction not authorized. Issuer system out of communication. Try again later. It may be a SITEF error, please check! | Your transaction cannot be processed. Try again later. If the error persists, contact the online store. | From the next day on, only 4 times within 16 days. | | AA | Time exceeded | Time exceeded in the communication with the issuing bank. Advise the cardholder to try again; if the error persists the cardholder will need to contact the issuing bank. | Time exceeded in the communication with the issuing bank. Try again later. If the error persists, contact your bank. | Only 4 times within 16 days. | | AF | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists there may be a problem with the merchant terminal, in which case the merchant should contact PayZu. | Transaction not allowed. Enter the card data again. If the error persists, contact the online store. | No | | AG | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists there may be a problem with the merchant terminal, in which case the merchant should contact PayZu. | Transaction not allowed. Enter the card data again. If the error persists, contact the online store. | No | | AH | Transaction not allowed. Credit card being used as debit. Use the credit function. | Transaction not allowed. Credit card being used as debit. Ask the cardholder to select the Credit Card payment option. | Transaction not authorized. Try again selecting the credit card payment option. | No | | AI | Transaction not authorized. Authentication was not performed. | Transaction not authorized. Authentication was not performed. The cardholder did not complete the authentication. Ask the cardholder to review the data and try again. If the error persists, contact PayZu providing the BIN (first 6 digits of the card) | Transaction not authorized. Authentication was not completed successfully. Try again and enter the requested data correctly. If the error persists, contact the merchant. | No | | AJ | Transaction not allowed. Credit or debit transaction in an operation that only allows Private Label. Try again selecting the Private Label option. | Transaction not allowed. Credit or debit transaction in an operation that only allows Private Label. Ask the cardholder to try again selecting the Private Label option. If the Private Label option is not available, check with PayZu whether your merchant account allows this operation. | Transaction not allowed. Credit or debit transaction in an operation that only allows Private Label. Try again and select the Private Label option. If a new error occurs, contact the online store. | No | | AV | Transaction not authorized. Invalid data | Failure validating the transaction data. Advise the cardholder to review the data and try again. | Data validation failure. Review the data provided and try again. | Only 4 times within 16 days. | | BD | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists there may be a problem with the merchant terminal, in which case the merchant should contact PayZu. | Transaction not allowed. Enter the card data again. If the error persists, contact the online store. | No | | BL | Transaction not authorized. Daily limit exceeded. | Transaction not authorized. Daily limit exceeded. Ask the cardholder to contact the issuing bank. | Transaction not authorized. Daily limit exceeded. Contact your issuing bank. | From the next day on, only 4 times within 16 days. | | BM | Transaction not authorized. Invalid card | Transaction not authorized. Invalid card. It may be a card block at the issuing bank or incorrect data. Try using the Luhn algorithm (Mod 10) to avoid transactions declined for this reason. | Transaction not authorized. Invalid card. Redo the transaction confirming the data provided. | No | | BN | Transaction not authorized. Card or account blocked. | Transaction not authorized. The cardholder's card or account is blocked. Ask the cardholder to contact the issuing bank. | Transaction not authorized. The cardholder's card or account is blocked. Contact your issuing bank. | No | | BO | Transaction not allowed. Operation failure. | Transaction not allowed. There was a processing error. Ask the cardholder to enter the card data again; if the error persists, contact the issuing bank. | Transaction not allowed. There was a processing error. Enter the card data again; if the error persists, contact the issuing bank. | Only 4 times within 16 days. | | BP | Transaction not authorized. Nonexistent checking account. | Transaction not authorized. Cannot process the transaction due to an error related to the cardholder's card or account. Ask the cardholder to contact the issuing bank. | Transaction not authorized. Cannot process the transaction due to an error related to the cardholder's card or account. Contact the issuing bank. | No | | BP171 | Rejected due to fraud risk (Velocity). | Related to Velocity rules | Try again after 1 hour. | Yes | | BP176 | Transaction not allowed. | The partner should check whether the integration process was completed successfully. | The partner should check whether the integration process was completed successfully. | N/A | | BP900 | Operation failure. | Related to a failure in the operation (request submission process). | Try again in 5 minutes. We recommend checking the transaction status before making a new authorization attempt. | Yes | | BP901 | Operation failure. | Related to a failure in the authorization. | Try again in 5 minutes. We recommend checking the transaction status before making a new authorization attempt. | Yes | | BP902 | Wait for the response of the previous operation. | Related to a failure in the capture. | Try again. | Yes | | BP903 | Cancellation failure. | Related to a failure in the cancellation. | Try again. | Yes | | BP904 | Query failure. | Related to a failure in the query. | Try again. | Yes | | BR | Transaction not authorized. Account closed | The cardholder's account is closed. Ask the cardholder to contact the issuing bank. | The cardholder's account is closed. Ask the cardholder to contact the issuing bank. | No | | C1 | Transaction not allowed. Card cannot process debit transactions. | Change the payment method or the card used. | Change the payment method or the card used. | No | | C2 | Transaction not allowed. | Incorrect data. Please review the data filled in on the payment screen. | Incorrect data. Please review the data filled in on the payment screen. | No | | C3 | Transaction not allowed. | Invalid period for this type of transaction. | Invalid period for this type of transaction. | No | | CF | Transaction not authorized. Data validation failure. | Transaction not authorized. Data validation failure. Ask the cardholder to contact the issuing bank. | Transaction not authorized. Data validation failure. Contact the issuing bank. | No | | CG | Transaction not authorized. Data validation failure. | Transaction not authorized. Data validation failure. Ask the cardholder to contact the issuing bank. | Transaction not authorized. Data validation failure. Contact the issuing bank. | No | | DF | Transaction not allowed. Card failure or invalid card. | Transaction not allowed. Card failure or invalid card. Ask the cardholder to enter the card data again; if the error persists, contact the bank | Transaction not allowed. Card failure or invalid card. Enter the card data again; if the error persists, contact the bank | Only 4 times within 16 days. | | DM | Transaction not authorized. Limit exceeded/no balance. | Transaction not authorized. Limit exceeded/no balance. | Transaction not authorized. Contact your issuing bank. | From the next day on, only 4 times within 16 days. | | DQ | Transaction not authorized. Data validation failure. | Transaction not authorized. Data validation failure. Ask the cardholder to contact the issuing bank. | Transaction not authorized. Data validation failure. Contact the issuing bank. | No | | DS | Transaction not allowed for this card | Transaction not authorized. Transaction not allowed for this card. | Transaction not authorized. Contact your issuing bank. | Only 4 times within 16 days. | | EB | Number of installments higher than allowed. | Transaction not authorized. Contact PayZu and check whether your account has installments enabled. | Transaction not authorized. Contact PayZu and check whether your account has installments enabled. | Yes | | EE | Transaction not allowed. Installment amount below the allowed minimum. | Transaction not allowed. Installment amount below the allowed minimum. Installments below R$ 5.00 are not allowed. The installment calculation needs to be reviewed. | Transaction not allowed. The installment amount is below the allowed minimum. Contact the online store. | No | | EK | Transaction not allowed for this card | Transaction not authorized. Transaction not allowed for this card. | Transaction not authorized. Contact your issuing bank. | Only 4 times within 16 days. | | FC | Transaction not authorized. Call the issuer | Transaction not authorized. Advise the cardholder to contact the issuing bank. | Transaction not authorized. Contact your issuing bank. | No | | FE | Transaction not authorized. Mismatch in the transaction/payment date. | Transaction not authorized. Invalid transaction date or first payment date. | Transaction not authorized. Redo the transaction confirming the data. | No | | FF | Cancellation OK | Cancellation transaction authorized successfully. ATTENTION: this return applies to cancellations, not to authorizations. | Cancellation transaction authorized successfully | No | | FG | Transaction not authorized. Call AmEx 08007285090. | Transaction not authorized. Advise the cardholder to contact the AmEx service center. | Transaction not authorized. Contact the AmEx service center at 08007285090 | No | | GA | Wait for contact | Transaction not authorized. Referred by Lynx Online as a preventive measure. | Transaction not authorized. The merchant should wait for contact from PayZu | No | | GF | Transaction denied. | Transaction not authorized. Check whether the provided IP is allowed to process the transaction | Transaction not allowed. Contact PayZu. | No | | GD | Transaction not allowed. | Transaction not allowed. Contact PayZu. | Transaction not allowed. Contact PayZu. | N/A | | GT | Transaction denied. | Brute force attack. | Transaction not allowed. Contact PayZu. | No | | GK | Transaction denied. | Temporary block due to a brute force attack. | Transaction not allowed. Contact PayZu. | No | | HJ | Transaction not allowed. Invalid operation code. | Transaction not allowed. Invalid Coban operation code. | Transaction not allowed. Invalid Coban operation code. Contact the merchant. | No | | IA | Transaction not allowed. Invalid operation indicator. | Transaction not allowed. Invalid Coban operation indicator. | Transaction not allowed. Invalid Coban operation indicator. Contact the merchant. | No | | KA | Transaction not allowed. Data validation failure. | Transaction not allowed. There was a data validation failure. Ask the cardholder to review the data and try again. If the error persists, check the communication between the online store and PayZu. | Transaction not allowed. There was a data validation failure. Review the data provided and try again. If the error persists, contact the online store. | No | | KB | Transaction not allowed. Incorrect option selected. | Transaction not allowed. Incorrect option selected. Ask the cardholder to review the data and try again. If the error persists, check the communication between the online store and PayZu. | Transaction not allowed. Incorrect option selected. Try again. If the error persists, contact the online store. | No | | KE | Transaction not authorized. Data validation failure. | Transaction not authorized. Data validation failure. The selected option is not enabled. Check the options available for the cardholder. | Transaction not authorized. Data validation failure. The selected option is not enabled. Contact the online store. | No | | NR | Transaction not allowed. | Transaction not allowed. | Transaction not allowed. Retry the transaction after 30 days | Retry the transaction after 30 days. | | RP | Transaction not allowed. | Transaction not allowed. | Transaction not allowed. Retry the transaction after 72h | Retry the transaction after 72 hours. | | SC | Transaction not allowed. | Transaction not allowed. Recurring payment, service canceled. Do not retry. | Transaction not allowed. Recurring payment, service canceled. Do not retry. | No. | | U3 | Transaction not allowed. Data validation failure. | Transaction not allowed. There was a data validation failure. Ask the cardholder to review the data and try again. If the error persists, check the communication between the online store and PayZu. | Transaction not allowed. There was a data validation failure. Review the data provided and try again. If the error persists, contact the online store. | No | | 6P | Transaction not authorized. Invalid data | Failure validating the transaction data. Advise the cardholder to review the data and try again. | Data validation failure. Review the data provided and try again. | Only 4 times within 16 days | # Programa de retentativa das bandeiras (/docs/cartao/retry-program) ## O que são retentativas? [#o-que-são-retentativas] Quando um cliente tenta realizar uma compra com cartão em sua loja, a transação pode ser negada por diversos motivos. As tentativas subsequentes de concluir a transação com o mesmo cartão são chamadas de retentativas. As transações de compra com cartão (presente ou não presente) e as de Zero Auth (validação do cartão) estão sujeitas às regras das bandeiras para retentativas. ### Valores e limites por bandeira [#valores-e-limites-por-bandeira] Cada bandeira de cartão estabelece valores específicos para as retentativas, e a quantidade de tentativas permitidas antes de cobrar taxas também varia conforme a bandeira. ### Cartão presente e não presente [#cartão-presente-e-não-presente] As bandeiras definem regras distintas para transações com cartão presente e não presente, como no caso das vendas online. ### Penalidades por exceder os limites [#penalidades-por-exceder-os-limites] Os e-commerces que não seguirem as regras de retentativa podem ser penalizados com a cobrança de tarifas adicionais por transações excedidas, conforme o programa de cada bandeira. ## Recusas reversíveis e irreversíveis [#recusas-reversíveis-e-irreversíveis] Com o objetivo de melhorar a experiência de compra, o mercado de meios de pagamento, em parceria com a ABECS, implementou a padronização dos códigos de resposta para transações recusadas com cartão. As tentativas de retentativa foram classificadas em dois tipos, irreversível e reversível. **Irreversível: nunca realizar retentativa** Esse tipo de recusa indica que o cartão está cancelado, foi perdido ou roubado, há uma fraude confirmada ou a transação não é permitida para o produto específico. Em qualquer uma dessas situações, o emissor nunca concederá uma aprovação. Se uma tentativa de autorização ocorrer após uma recusa irreversível, sem alteração de qualquer dado na solicitação, a transação continuará a ser negada. **Reversível: permitido realizar retentativa** Neste caso, o emissor pode, eventualmente, aprovar a transação, mas não o faz naquele momento, devido a problemas temporários como falha no sistema, falta de limite disponível, suspeita de fraude ou um número excessivo de tentativas incorretas de digitação da senha. Essas recusas são temporárias e podem ser alteradas com o tempo, permitindo a aprovação em uma nova tentativa. As bandeiras Visa, Mastercard e Elo ajustaram suas regras para limitar a quantidade de tentativas de autorização em transações negadas. Essas mudanças estabelecem a cobrança de tarifas quando o número de tentativas excede o limite permitido. Confira a seguir as regras específicas de cada bandeira. ## Mastercard [#mastercard] A bandeira Mastercard possui o programa Transaction Processing Excellence (TPE), que engloba duas categorias: 1. Excessive Attempts: monitora as retentativas de transações negadas nos ambientes de cartão presente e cartão não presente. Válido tanto para códigos de negadas reversíveis quanto irreversíveis. 2. Merchant Advice Code Transaction Excellence (MAC): monitora as retentativas de transações negadas, nos ambientes de cartão não presente e que são irreversíveis. Haverá cobrança somente nos MACs 03 e 21. ### Excessive Attempts [#excessive-attempts] São cobranças efetuadas quando o estabelecimento comercial excede as regras de retentativas de transações. A bandeira também realiza o monitoramento para qualquer autorização de valor nominal, aprovada, com estorno subsequente para transações abaixo de 1 unidade de moeda inteira ou o equivalente a US$ 1. O monitoramento é aplicado para as retentativas de transações de compras negadas e aprovadas, realizadas em ambiente de cartão presente e cartão não presente. Tabela Excessive Attempts: | Categorias | Códigos | Vigência | Tarifa Doméstica | Tarifa Internacional | Quando Ocorre | Permitido Retentar | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------- | -------------------- | ------------------------ | -------------------------- | | Cartão presente e cartão não presente | Qualquer código de negativa que não está atribuído ao MAC 03 e 21. E também os códigos MAC caso não respeite os limites do "Excessive Attempts" | Até 31/01/2023 | R$ 2,00 | \* | A partir 11ª retentativa | Permitido retentar em 24h. | | Cartão presente e cartão não presente | Qualquer código de negativa que não está atribuído ao MAC 03 e 21. E também os códigos MAC caso não respeite os limites do "Excessive Attempts" | Vigente desde 01/02/2023 | R$ 2,00 | \* | A partir 8ª retentativa | Permitido retentar em 24h. | * Serão consideradas como retentativas todas as transações de pagamento no mesmo cartão, e mesmo número de estabelecimento; * A Mastercard prorrogou a data de vigência para o dia 01/02/2023 referente às novas regras do programa (Excessive Attempts), antes prevista para início do dia 01/11/2022. Confira as mudanças: 1. O excesso considerado no programa ocorrerá a partir da oitava retentativa dentro do mês de apuração; os valores cobrados sofreram alteração. 2. E a Mastercard também está introduzindo um limite de 35 tentativas negadas no mesmo cartão e mesmo número de estabelecimento por período contínuo de 30 dias. Mesmo se a loja não ultrapassar o limite de sete retentativas no período de 24h, mas ultrapassar a quantidade do limite mensal, a cobrança será aplicada. A regra vigente do programa Excessive Attempts está em vigor desde 01/02/2023 (tabela Excessive Attempts): a cobrança se aplica a partir da 8ª retentativa da mesma transação (mesmo cartão e mesmo número de estabelecimento), sendo permitido retentar após 24 horas. Até 31/01/2023 valia a regra anterior, que permitia 10 tentativas antes da cobrança. ### Merchant Advice Code Transaction Excellence (MAC) [#merchant-advice-code-transaction-excellence-mac] São cobranças efetuadas quando o estabelecimento comercial realiza retentativa de envio de autorização para códigos de respostas irreversíveis com um mesmo cartão, válido para cartão não presente. Dentro desse programa de retentativas, há programas que se destinam especificamente ao cenário de "Não tente esta transação novamente". Para esses casos, a Mastercard identifica as transações com os valores MAC 03 e MAC 21, por exemplo. O programa MAC comporta alguns valores, porém somente os MACs 03 e 21 possuem uma cobrança específica. Os demais MACs não se enquadram nessa cobrança. Os outros códigos MAC (01, 02, 04, 24, 25, 26, 27, 28, 29, 30, 40 e 41) não entram no programa de cobrança do MAC, mas entram na cobrança do programa Excessive Attempts, caso exceda os limites. Desde 14/10/2022 a Mastercard introduziu novos códigos MAC (24, 25, 26, 27, 28, 29 e 30) quando um emissor recusa uma transação com o código de resposta 51 (insuficiência de fundos) seguido de um dos MAC da tabela a seguir, para que o comerciante tome a melhor ação. Tabela com toda a relação de MACs: | MAC | Descrição | Observação | | --- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Informações da nova conta disponíveis (ABU) | Necessidade de realizar atualização dos dados da conta que está sendo utilizada na transação, usando o ABU, por exemplo. | | 02 | Não pode aprovar no momento, tente depois | Tente novamente a transação após 72 horas ou tente a transação com um método de pagamento diferente. | | 03 | Não é permitido retentar | Busque outro meio de garantir o pagamento, evitando custos desnecessários de várias solicitações de autorização que continuarão a resultar em declínios. | | 04 | Requisitos de token não atendidos para este token modelo | Há necessidade de revisar os requisitos de token, pois os requisitos não foram atendidos para este token modelo enviado na transação. | | 21 | Plano cancelado | Comprador realiza cancelamento de plano e mesmo após o cancelamento, estabelecimento continua enviando solicitação de autorização de compra. | | 24 | Tente novamente após 1 hora | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 25 | Tente novamente após 24 horas | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 26 | Tente novamente após 2 dias | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 27 | Tente novamente após 4 dias | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 28 | Tente novamente após 6 dias | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 29 | Tente novamente após 8 dias | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 30 | Tente novamente após 10 dias | Válido somente para o código de resposta 51 (insuficiência de fundos). | | 40 | Não é permitido retentar | Cartão pré pago não recarregável para consumo. | | 41 | Não é permitido retentar | Cartão virtual de uso único do consumidor. | Além disso, alguns códigos de retorno deixarão de ser enviados: * 04 (Cartão de Captura) * 14 (Número de cartão inválido) * 43 (Cartão Roubado) * 54 (Cartão Expirado) * 57 (Transação Não Permitida) * 62 (Cartão Restrito) * 63 (Violação de Segurança) **Categorização de retornos Mastercard** A Mastercard poderá consolidar alguns códigos de respostas dos emissores, que muitas vezes não indicam ao comerciante se pode ou não retentar, em três códigos de uso exclusivo Mastercard: * 79 (Ciclo de vida); * 82 (Política); * 83 (Fraude/Segurança). Os códigos originais serão substituídos pelo Merchant Advice Code (MAC), que acompanharão os códigos 79, 82 e 83 para determinar se a transação pode ou não ser retentada. Por exemplo: | Quando | Então | E o código de resposta | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------- | | O emissor recusar a transação usando o código de resposta 54 (Cartão Expirado) | A Mastercard substituirá o código 54 para o código 79 (recusa por ciclo de vida) | Acompanha o devido Merchant Advice Code (MAC) | **Programa de retentativas MAC 03 e MAC 21** Forma de apuração: * Serão consideradas as transações de cartão não presente; * São consideradas como retentativas todas as transações de pagamento no mesmo cartão e mesmo número de estabelecimento; * São contabilizadas as retentativas no programa MAC com os valores MAC 03 e MAC 21; * Válido para qualquer código de resposta; * O excesso contabilizado no programa ocorrerá a partir da 1ª retentativa dentro do mês de apuração; * O contador é zerado após o período de 30 dias; * As retentativas podem ser cobradas nos MACs 03/21 e no Excessive Attempts caso ultrapasse o limite de cada programa; * A tarifa aplicada era de R$ 1,25 e, a partir de 01 de janeiro de 2023, passou a vigorar o valor listado a seguir. Tabela de valores: | Número de retentativa | Regra | | ----------------------- | -------------------------------------------------------------------------------------- | | A partir 1ª retentativa | R$ 2,50 (dois reais e cinquenta centavos) por retentativa, a partir da 1ª retentativa. | ## Visa [#visa] O programa de retentativas instituído pela bandeira Visa gera cobranças quando o estabelecimento comercial excede as regras de retentativas. O objetivo é criar um equilíbrio no ecossistema de transações a fim de garantir que os credenciadores e estabelecimentos forneçam informações precisas sobre as retentativas e diminuam novas tentativas desnecessárias. A bandeira exige que os emissores usem códigos de resposta corretos e não genéricos, para facilitar a identificação do motivo da recusa de uma transação. A Visa divide esses códigos em reversíveis e irreversíveis, sendo válido tanto para transações com cartão presente e cartão não presente: * Códigos reversíveis: são permitidas até 20 tentativas de aprovar uma mesma transação (com mesmo cartão, transação, validade, valor e estabelecimento) no período de 30 dias. Após os 30 dias, a contar da primeira tentativa, qualquer retentativa será cobrada. Passado o período de 30 dias, no envio de uma retentativa da mesma transação, a cobrança já será aplicada. Dessa forma, a regra de 20 tentativas deixa de ser válida, passando a ser válido o período de 30 dias corridos. * Códigos irreversíveis: é permitida apenas a 1ª tentativa de aprovar a transação (com mesmo cartão, transação, validade, valor e estabelecimento). Na segunda tentativa, a transação já será cobrada, independente do período em que for realizada. Tarifas: ao ultrapassar os limites de tentativas estabelecidos pela bandeira, haverá uma cobrança de tarifa para cada transação excedente. * Doméstico: USD 0,10 + 13,83% de imposto; * Estrangeiro: USD 0,25 + 13,83% de imposto. A cobrança de tarifas é aplicada desde abril de 2021. A Visa agrupou os códigos de retorno em quatro categorias: * **Categoria 1: emissor nunca aprovará.** Indica que o cartão foi cancelado ou nunca existiu ou que a negativa é resultado de uma restrição permanente ou condição de erro que impedirá uma aprovação futura. * **Categoria 2: emissor não pode aprovar no momento.** Indica que a negativa é resultado de uma condição temporária tal como risco de crédito, controles de velocidade do emissor ou outras restrições do cartão que podem permitir uma retentativa da transação ser aprovada. Em alguns casos, a negativa requer uma ação do portador ou emissor para remover a restrição antes que uma aprovação possa ser obtida. * **Categoria 3: qualidade de dados.** Quando um erro de dados é identificado pelo emissor, essa transação é declinada como consequência. Os estabelecimentos devem revalidar dados de pagamentos antes de retentar. Estabelecimentos e credenciadores devem monitorar estes códigos de negativas devido à exposição potencial a fraudes. Atenção: a categoria 3 tem, além dos limites considerados na categoria 2, um limite diferente que é cumulativo. Um estabelecimento pode realizar até 25.000 transações em um período de 30 dias (neste caso considerando apenas o número do estabelecimento e códigos de negadas). Se ultrapassar o limite, todas as transações recusadas por categoria 3 serão tarifadas. * **Categoria 4: códigos de respostas genéricos.** A categoria 4 inclui todos os demais códigos de resposta de recusa que não estão nas categorias 1, 2 e 3, pois pode haver circunstâncias em que não haja valor de código de resposta para uma condição de recusa específica. Emissores podem usar outros valores de códigos de resposta definidos nas Especificações Técnicas VisaNet; no entanto, o uso deve permanecer mínimo. Os emissores devem usar códigos de resposta que reflitam com mais precisão o motivo das recusas. Ou seja, focar nas categorias 1 (o emissor nunca aprovará), 2 (o emissor não pode aprovar neste momento) e 3 (qualidade dos dados) e evitar usar a 4 (código de resposta genérico). Os emissores devem limitar essa categoria ao máximo. A taxa da Categoria 4 é cobrada para garantir que não mais do que a porcentagem aprovada regionalmente do total de recusas do emissor sejam categorizadas como Categoria 4. Os emissores que excederem o limite definido regionalmente receberão a Taxa de Código de Resposta Genérica por base de transação para cada declínio em excesso do limite definido. Tabela com as regras e códigos de recusa. As regras da tabela a seguir são válidas tanto para transações de compra, quanto para transações Zero Auth: | Categoria | Tipo | Códigos | Regras | | --------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Categoria 1
Emissor não aprovará novas tentativas | Irreversível | 04 - Reter cartão
07 - Reter cartão, condições especiais
12 - Transação inválida
14\* - Número de conta inválido
15 - Emissor não existe
41 - Reter cartão (cartão perdido)
43 - Reter cartão (cartão roubado)
46 - Conta encerrada
57 - Transação não permitida ao portador de cartão
R0 - Parar ordem de pagamento
R1 - Revogação do pedido de autorização
R3 - Revogação de todos os pedidos de autorização | Cobrança de tarifa a partir da 2ª tentativa. | | Categoria 2
Emissor não aprovará no momento; novas tentativas são permitidas | Reversível | 03 - Comerciante inválido
19 - Redigitar a transação
39\*\* - Sem conta de crédito
51 - Insuficiência de fundos
52\*\* - Sem conta corrente
53\*\* - Sem conta poupança
59 - Suspeita de fraude
61 - Excede os limites de valor de retiradas
62 - Cartão restrito (cartão inválido na região ou país)
65 - Excede a frequência de retiradas
75 - Excedeu o número permitido de tentativas de digitação de senha
78 - Bloqueado, usado pela primeira vez ou condição especial (a conta está temporariamente bloqueada)
86 - Mal funcionamento no caixa eletrônico
91 - Emissor ou switch inoperante
93 - A transação não pode ser concluída (violação da lei)
96 - Mal funcionamento do sistema
N3 - Serviço de saque indisponível
N4 - Solicitação de dinheiro excede o limite do emissor
Z5\*\*\* - Conta válida, mas valor não suportado
5C\*\*\*\* - Transação não suportada/bloqueada pelo emissor
9G\*\*\*\* - Bloqueado pelo portador do cartão (contate o portador do cartão). | Cobrança de tarifa a partir da 16ª tentativa: o estabelecimento pode retentar a mesma transação 15 vezes.
A partir da 16ª tentativa (com mesmo cartão, transação, validade, valor e estabelecimento) num período de 30 dias corridos a partir da 1ª tentativa, a transação será tarifada. Passado o período de 30 dias, a Visa não permite nenhuma nova tentativa. Então, caso haja envio de uma tentativa dessa mesma transação, a cobrança já será aplicada para essa retentativa enviada (daí, a regra de 15 tentativas deixa de ser válida, passando a ser válido o período de 30 dias corridos). | | Categoria 3
Qualidade de dados | Reversível | 54 - Cartão vencido
55 - Senha incorreta
70 - Dados de PIN necessários (somente na região da Europa)
82 - Os resultados de CAM, dCVV, iCVV ou CVV on-line foram negativos
1A - Autenticação de cliente adicional necessária (somente na região da Europa)
6P - Falha na verificação (a identificação do titular do cartão não corresponde aos registros do emissor)
N7 - Recusa decorrente de falha do CVV2 (Visa) | Cobrança de tarifa a partir da 16ª tentativa: o estabelecimento pode retentar a mesma transação 15 vezes.
A partir da 16ª tentativa (com mesmo cartão, transação, validade, valor e estabelecimento) num período de 30 dias corridos a partir da 1ª tentativa, a transação será tarifada. Passado o período de 30 dias, a Visa não permite nenhuma nova tentativa. Então, caso haja envio de uma tentativa dessa mesma transação, a cobrança já será aplicada para essa retentativa enviada (daí, a regra de 15 tentativas deixa de ser válida, passando a ser válido o período de 30 dias corridos). | | Categoria 4
Códigos de respostas genéricos | Reversível | Códigos de respostas genéricos não listados nas categorias 1, 2, 3 | Cobrança de tarifa a partir da 16ª tentativa: o estabelecimento pode retentar a mesma transação 15 vezes.
A partir da 16ª tentativa (com mesmo cartão, transação, validade, valor e estabelecimento) num período de 30 dias corridos a partir da 1ª tentativa, a transação será tarifada. Passado o período de 30 dias, a Visa não permite nenhuma nova tentativa. Então, caso haja envio de uma tentativa dessa mesma transação, a cobrança já será aplicada para essa retentativa enviada (daí, a regra de 15 tentativas deixa de ser válida, passando a ser válido o período de 30 dias corridos). | Desde abril de 2023, o limite permitido da contagem total de recusas para a categoria 3 passou de 10.000 para 25.000 recusas em um ciclo de faturamento de 30 dias. ## Elo [#elo] As regras apresentadas a seguir entraram em vigor em janeiro de 2025. O objetivo da mudança é garantir que os estabelecimentos e credenciadores diminuam novas tentativas de aprovações desnecessárias. O período de apuração das transações ocorre mensalmente, sendo contabilizado do 1º ao último dia corrido do mês de violação. Confira os valores: | Cobrança | | ------------------------------------------------------ | | R$ 0,80 (oitenta centavos) por cada tentativa excedida | ### Regras de cobrança por grupo [#regras-de-cobrança-por-grupo] A bandeira vai considerar códigos reversíveis e irreversíveis de acordo com grupos separados em três categorias. Abaixo estão as alterações que entraram em vigência: | Grupo | Descrição | Cobrança | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Grupo 1 | Transações de cartão não presente negadas com códigos irreversíveis, considerando o mesmo número de cartão, mesmo CNPJ do estabelecimento e mesmo valor. | A cobrança ocorre a partir da 2ª retentativa dentro do mês de apuração. | | Grupo 2 | Transações de cartão não presente negadas com códigos reversíveis. | A cobrança ocorre a partir da 16ª retentativa dentro do mês de apuração. | | Grupo 3 | Transações de cartão não presente negadas com características de Ataques de Força Bruta, considerando transações com o mesmo CNPJ Raiz do Estabelecimento Comercial. | Ocorre a partir de 10.001 transações negadas (dentro da categoria de códigos) e que excedam 5% do total de recusas, a depender do volume de transações de pagamento do CNP envolvido. | Classificação dos grupos: | Grupo 1
Emissor nunca aprovará (IRREVERSÍVEL) | Grupo 2
Emissor não pode aprovar no momento (REVERSÍVEL) | Grupo 3
Qualidade de dados, revalidar informação (\*) | | -------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- | | 57 - Não permitida | 51 - Limite insuficiente | 54 - Cartão Expirado | | 14 ou 56 - Cartão Inválido (\*) | 59 - Suspeita de fraude | 55 - Senha Inválida | | 58 - Comerciante Inválido | 04 - Refazer a transação | 82 - Cartão criptograma inválido | | 46 - Conta encerrada | 06 - Consultar credenciador | 63 - CVE inválido ou não presente | | FM - Utilizar o Chip | 38 - Excedidas tentativas de senha compras | | | 19 - Consultar adquirente | 61 - Valor em excesso de saque | | | 12 - Erro no cartão | 62 - Bloqueio temporário de inadimplência | | | 30 - Erro de formato Mensageria | 65 - Quantidade de saque excedida | | | 13 - Valor transação inválido | 75 - Excedidas tentativas de senha / saque | | | 23 - Valor da Parcela Inválido | 78 - Cartão novo sem desbloqueio ou bloqueado pelo cliente APP/NFC/E-COM | | | 41 - Cartão Perdido | 91 - Emissor fora do ar | | | 43 - Cartão Roubado | | | | 64 - Valor mínimo da transação inválido | | | | 83 - Erro de criptografia senha | | | | 76 - Conta destino inválida | | | | 77 - Conta origem inválida | | | ## Demais bandeiras [#demais-bandeiras] * Códigos reversíveis: serão permitidas novas retentativas para o mesmo cliente e cartão. Não há limite e período pré-estabelecido. Importante: antes de realizar uma nova tentativa, siga a orientação recebida na resposta da transação negada. * Códigos irreversíveis: não serão permitidas autorizações para o mesmo cartão ou estabelecimento, depois de receber a 1ª resposta de recusa do emissor. ## Retentativa por código de retorno [#retentativa-por-código-de-retorno] A tabela a seguir relaciona os códigos retornados em `returnCode`, o significado, a ação recomendada e se a retentativa é permitida. | Código Resposta | Definição | Significado | Ação | Permite Retentativa | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | 0 | Transação autorizada com sucesso. | Transação autorizada com sucesso. | Transação autorizada com sucesso. | Não | | 002 | Credenciais inválidas | Existe algum bloqueio do terminal na PayZu | Entre em contato com o suporte e-commerce PayZu | Sim | | 2 | Transação não autorizada. Transação referida. | Transação não autorizada. Referida (suspeita de fraude) pelo banco emissor. | Transação não autorizada. Entre em contato com seu banco emissor. | Não | | 9 | Transação cancelada parcialmente com sucesso. | Transação cancelada parcialmente com sucesso | Transação cancelada parcialmente com sucesso | Não | | 11 | Transação autorizada com sucesso para cartão emitido no exterior | Transação autorizada com sucesso. | Transação autorizada com sucesso. | Não | | 21 | Cancelamento não efetuado. Transação não localizada. | Não foi possível processar o cancelamento. Se o erro persistir, entre em contato com a PayZu. | Não foi possível processar o cancelamento. Tente novamente mais tarde. Persistindo o erro, entrar em contato com a loja virtual. | Não | | 22 | Parcelamento inválido. Número de parcelas inválidas. | Não foi possível processar a transação. Número de parcelas inválidas. Se o erro persistir, entre em contato com a PayZu. | Não foi possível processar a transação. Valor inválido. Refazer a transação confirmando os dados informados. Persistindo o erro, entrar em contato com a loja virtual. | Não | | 24 | Quantidade de parcelas inválido. | Não foi possível processar a transação. Quantidade de parcelas inválido. Se o erro persistir, entre em contato com a PayZu. | Não foi possível processar a transação. Quantidade de parcelas inválido. Refazer a transação confirmando os dados informados. Persistindo o erro, entrar em contato com a loja virtual. | Não | | 60 | Transação não autorizada. | Transação não autorizada. Tente novamente. Se o erro persistir o portador deve entrar em contato com o banco emissor. | Não foi possível processar a transação. Tente novamente mais tarde. Se o erro persistir, entre em contato com seu banco emissor. | Apenas 4 vezes em 16 dias. | | 67 | Transação não autorizada. Cartão bloqueado para compras hoje. | Transação não autorizada. Cartão bloqueado para compras hoje. Bloqueio pode ter ocorrido por excesso de tentativas inválidas. O cartão será desbloqueado automaticamente à meia noite. | Transação não autorizada. Cartão bloqueado temporariamente. Entre em contato com seu banco emissor. | A partir do dia seguinte, apenas 4 vezes em 16 dias. | | 70 | Transação não autorizada. Limite excedido/sem saldo. | Transação não autorizada. Limite excedido/sem saldo. | Transação não autorizada. Entre em contato com seu banco emissor. | A partir do dia seguinte, apenas 4 vezes em 16 dias. | | 72 | Cancelamento não efetuado. Saldo disponível para cancelamento insuficiente. | Cancelamento não efetuado. Saldo disponível para cancelamento insuficiente. Se o erro persistir, entre em contato com a PayZu. | Cancelamento não efetuado. Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. | Não | | 79 | Transação Mastercard não permitida para o cartão | Transação não autorizada. Não é possível processar a transação devido a erro relacionado ao cartão do portador. Solicite ao portador que entre em contato com o banco emissor. | Entre em contato com o seu banco | Não | | 80 | Transação não autorizada. Divergência na data de transação/pagamento. | Transação não autorizada. Data da transação ou data do primeiro pagamento inválida. | Transação não autorizada. Refazer a transação confirmando os dados. | Não | | 82 | Transação Mastercard não autorizada. Ligue para o emissor | Transação não autorizada devido a regras do emissor. Oriente o portador a entrar em contato com o banco emissor. | Entre em contato com o seu banco | Não | | 83 | Transação Mastercard suspeita de fraude | Transação não autorizada. Suspeita de fraude pelo banco emissor. | Entre em contato com o seu banco | Não | | 85 | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a PayZu. | Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. | Não | | 89 | Erro na transação. | Transação não autorizada. Erro na transação. O portador deve tentar novamente e se o erro persistir, entrar em contato com o banco emissor. | Transação não autorizada. Erro na transação. Tente novamente e se o erro persistir, entre em contato com seu banco emissor. | Apenas 4 vezes em 16 dias. | | 90 | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a PayZu. | Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. | Não | | 97 | Valor não permitido para essa transação. | Transação não autorizada. Valor não permitido para essa transação. | Transação não autorizada. Valor não permitido para essa transação. | Não | | 98 | Sistema/comunicação indisponível. | Transação não autorizada. Sistema do emissor sem comunicação. Se for geral, verificar SITEF, GATEWAY e/ou Conectividade. | Sua Transação não pode ser processada, Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. | Apenas 4 vezes em 16 dias. | | 475 | Timeout de Cancelamento | A aplicação não respondeu dentro do tempo esperado. | Realizar uma nova tentativa após alguns segundos. Persistindo, entrar em contato com o Suporte. | Não | | 999 | Sistema/comunicação indisponível. | Transação não autorizada. Sistema do emissor sem comunicação. Tente mais tarde. Pode ser erro no SITEF, favor verificar ! | Sua Transação não pode ser processada, Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. | A partir do dia seguinte, apenas 4 vezes em 16 dias. | | AA | Tempo Excedido | Tempo excedido na comunicação com o banco emissor. Oriente o portador a tentar novamente, se o erro persistir será necessário que o portador contate seu banco emissor. | Tempo excedido na sua comunicação com o banco emissor, tente novamente mais tarde. Se o erro persistir, entre em contato com seu banco. | Apenas 4 vezes em 16 dias. | | AF | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a PayZu. | Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. | Não | | AG | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a PayZu. | Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. | Não | | AH | Transação não permitida. Cartão de crédito sendo usado com débito. Use a função crédito. | Transação não permitida. Cartão de crédito sendo usado com débito. Solicite ao portador que selecione a opção de pagamento Cartão de Crédito. | Transação não autorizada. Tente novamente selecionando a opção de pagamento cartão de crédito. | Não | | AI | Transação não autorizada. Autenticação não foi realizada. | Transação não autorizada. Autenticação não foi realizada. O portador não concluiu a autenticação. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir, entre em contato com a PayZu informando o BIN (6 primeiros dígitos do cartão) | Transação não autorizada. Autenticação não foi realizada com sucesso. Tente novamente e informe corretamente os dados solicitado. Se o erro persistir, entre em contato com o lojista. | Não | | AJ | Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Tente novamente selecionando a opção Private Label. | Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Solicite ao portador que tente novamente selecionando a opção Private Label. Caso não disponibilize a opção Private Label verifique na PayZu se o seu estabelecimento permite essa operação. | Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Tente novamente e selecione a opção Private Label. Em caso de um novo erro entre em contato com a loja virtual. | Não | | AV | Transação não autorizada. Dados Inválidos | Falha na validação dos dados da transação. Oriente o portador a rever os dados e tentar novamente. | Falha na validação dos dados. Reveja os dados informados e tente novamente. | Apenas 4 vezes em 16 dias. | | BD | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a PayZu. | Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. | Não | | BL | Transação não autorizada. Limite diário excedido. | Transação não autorizada. Limite diário excedido. Solicite ao portador que entre em contato com seu banco emissor. | Transação não autorizada. Limite diário excedido. Entre em contato com seu banco emissor. | A partir do dia seguinte, apenas 4 vezes em 16 dias. | | BM | Transação não autorizada. Cartão Inválido | Transação não autorizada. Cartão inválido. Pode ser bloqueio do cartão no banco emissor ou dados incorretos. Tente usar o Algoritmo de Luhn (Mod 10) para evitar transações não autorizadas por esse motivo. | Transação não autorizada. Cartão inválido. Refaça a transação confirmando os dados informados. | Não | | BN | Transação não autorizada. Cartão ou conta bloqueado. | Transação não autorizada. O cartão ou a conta do portador está bloqueada. Solicite ao portador que entre em contato com seu banco emissor. | Transação não autorizada. O cartão ou a conta do portador está bloqueada. Entre em contato com seu banco emissor. | Não | | BO | Transação não permitida. Falha da operação. | Transação não permitida. Houve um erro no processamento. Solicite ao portador que digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco emissor. | Transação não permitida. Houve um erro no processamento. Digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco emissor. | Apenas 4 vezes em 16 dias. | | BP | Transação não autorizada. Conta corrente inexistente. | Transação não autorizada. Não possível processar a transação por um erro relacionado ao cartão ou conta do portador. Solicite ao portador que entre em contato com o banco emissor. | Transação não autorizada. Não possível processar a transação por um erro relacionado ao cartão ou conta do portador. Entre em contato com o banco emissor. | Não | | BP171 | Rejeitada por risco de fraude (Velocity). | Está relacionado a regras do Velocity | Tente novamente após 1 hora. | Sim | | BP176 | Transação não permitida. | Parceiro deve checar se o processo de integração foi concluído com sucesso. | Parceiro deve checar se o processo de integração foi concluído com sucesso. | N/A | | BP900 | Falha na operação. | Está relacionado a alguma falha na operação (processo de envio da requisição). | Tente novamente em 5 minutos. Recomendamos realizar a consulta do status da transação antes de fazer uma nova tentativa de autorização. | Sim | | BP901 | Falha na operação. | Está relacionado a alguma falha na autorização. | Tente novamente em 5 minutos. Recomendamos realizar a consulta do status da transação antes de fazer uma nova tentativa de autorização. | Sim | | BP902 | Aguarde resposta da operação anterior. | Está relacionado a alguma falha na captura. | Tente novamente. | Sim | | BP903 | Falha no Cancelamento. | Está relacionado a alguma falha no cancelamento. | Tente novamente. | Sim | | BP904 | Falha na Consulta. | Está relacionado a alguma falha na consulta. | Tente novamente. | Sim | | BR | Transação não autorizada. Conta encerrada | A conta do portador está encerrada. Solicite ao portador que entre em contato com seu banco emissor. | A conta do portador está encerrada. Solicite ao portador que entre em contato com seu banco emissor. | Não | | C1 | Transação não permitida. Cartão não pode processar transações de débito. | Troque a modalidade de pagamento ou o cartão utilizado. | Troque a modalidade de pagamento ou o cartão utilizado. | Não | | C2 | Transação não permitida. | Dados incorretos. Favor rever os dados preenchidos na tela de pagamento. | Dados incorretos. Favor rever os dados preenchidos na tela de pagamento. | Não | | C3 | Transação não permitida. | Período inválido para este tipo de transação. | Período inválido para este tipo de transação. | Não | | CF | Transação não autorizada. Falha na validação dos dados. | Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. | Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. | Não | | CG | Transação não autorizada. Falha na validação dos dados. | Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. | Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. | Não | | DF | Transação não permitida. Falha no cartão ou cartão inválido. | Transação não permitida. Falha no cartão ou cartão inválido. Solicite ao portador que digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco | Transação não permitida. Falha no cartão ou cartão inválido. Digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco | Apenas 4 vezes em 16 dias. | | DM | Transação não autorizada. Limite excedido/sem saldo. | Transação não autorizada. Limite excedido/sem saldo. | Transação não autorizada. Entre em contato com seu banco emissor. | A partir do dia seguinte, apenas 4 vezes em 16 dias. | | DQ | Transação não autorizada. Falha na validação dos dados. | Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. | Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. | Não | | DS | Transação não permitida para o cartão | Transação não autorizada. Transação não permitida para o cartão. | Transação não autorizada. Entre em contato com seu banco emissor. | Apenas 4 vezes em 16 dias. | | EB | Número de parcelas maior que o Permitido. | Transação não autorizada. Entre em contato com a PayZu e verifique se o cadastro possui parcelamento liberado. | Transação não autorizada. Entre em contato com a PayZu e verifique se o cadastro possui parcelamento liberado. | Sim | | EE | Transação não permitida. Valor da parcela inferior ao mínimo permitido. | Transação não permitida. Valor da parcela inferior ao mínimo permitido. Não é permitido parcelas inferiores a R$ 5,00. Necessário rever cálculo para parcelas. | Transação não permitida. O valor da parcela está abaixo do mínimo permitido. Entre em contato com a loja virtual. | Não | | EK | Transação não permitida para o cartão | Transação não autorizada. Transação não permitida para o cartão. | Transação não autorizada. Entre em contato com seu banco emissor. | Apenas 4 vezes em 16 dias. | | FC | Transação não autorizada. Ligue Emissor | Transação não autorizada. Oriente o portador a entrar em contato com o banco emissor. | Transação não autorizada. Entre em contato com seu banco emissor. | Não | | FE | Transação não autorizada. Divergência na data de transação/pagamento. | Transação não autorizada. Data da transação ou data do primeiro pagamento inválida. | Transação não autorizada. Refazer a transação confirmando os dados. | Não | | FF | Cancelamento OK | Transação de cancelamento autorizada com sucesso. ATENÇÂO: Esse retorno é para casos de cancelamentos e não para casos de autorizações. | Transação de cancelamento autorizada com sucesso | Não | | FG | Transação não autorizada. Ligue AmEx 08007285090. | Transação não autorizada. Oriente o portador a entrar em contato com a Central de Atendimento AmEx. | Transação não autorizada. Entre em contato com a Central de Atendimento AmEx no telefone 08007285090 | Não | | GA | Aguarde Contato | Transação não autorizada. Referida pelo Lynx Online de forma preventiva. | Transação não autorizada. lojista deve aguardar contato por parte da PayZu | Não | | GF | Transação negada. | Transação não autorizada, verifique se o IP informado está liberado para processar a transação | Transação não permitida. Entre em contato com a PayZu. | Não | | GD | Transação não permitida. | Transação não permitida. Entre em contato com a PayZu. | Transação não permitida. Entre em contato com a PayZu. | N/A | | GT | Transação negada. | Ataque de força bruta. | Transação não permitida. Entre em contato com a PayZu. | Não | | GK | Transação negada. | Bloqueio temporário por ataque de força bruta. | Transação não permitida. Entre em contato com a PayZu. | Não | | HJ | Transação não permitida. Código da operação inválido. | Transação não permitida. Código da operação Coban inválido. | Transação não permitida. Código da operação Coban inválido. Entre em contato com o lojista. | Não | | IA | Transação não permitida. Indicador da operação inválido. | Transação não permitida. Indicador da operação Coban inválido. | Transação não permitida. Indicador da operação Coban inválido. Entre em contato com o lojista. | Não | | KA | Transação não permitida. Falha na validação dos dados. | Transação não permitida. Houve uma falha na validação dos dados. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir verifique a comunicação entre loja virtual e PayZu. | Transação não permitida. Houve uma falha na validação dos dados. reveja os dados informados e tente novamente. Se o erro persistir entre em contato com a Loja Virtual. | Não | | KB | Transação não permitida. Selecionado a opção incorrente. | Transação não permitida. Selecionado a opção incorreta. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir deve ser verificado a comunicação entre loja virtual e PayZu. | Transação não permitida. Selecionado a opção incorreta. Tente novamente. Se o erro persistir entre em contato com a Loja Virtual. | Não | | KE | Transação não autorizada. Falha na validação dos dados. | Transação não autorizada. Falha na validação dos dados. Opção selecionada não está habilitada. Verifique as opções disponíveis para o portador. | Transação não autorizada. Falha na validação dos dados. Opção selecionada não está habilitada. Entre em contato com a loja virtual. | Não | | NR | Transação não permitida. | Transação não permitida. | Transação não permitida. Retentar a transação após 30 dias | Retentar a transação após 30 dias. | | RP | Transação não permitida. | Transação não permitida. | Transação não permitida. Retentar a transação após 72h | Retentar a transação após 72 horas. | | SC | Transação não permitida. | Transação não permitida. Pagamento recorrente, serviço cancelado. Não retentar. | Transação não permitida. Pagamento recorrente, serviço cancelado. Não retentar. | Não. | | U3 | Transação não permitida. Falha na validação dos dados. | Transação não permitida. Houve uma falha na validação dos dados. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir verifique a comunicação entre loja virtual e PayZu. | Transação não permitida. Houve uma falha na validação dos dados. reveja os dados informados e tente novamente. Se o erro persistir entre em contato com a Loja Virtual. | Não | | 6P | Transação não autorizada. Dados Inválidos | Falha na validação dos dados da transação. Oriente o portador a rever os dados e tentar novamente. | Falha na validação dos dados. Reveja os dados informados e tente novamente. | Apenas 4 vezes em 16 dias | # 卡组织重试计划 (/docs/cartao/retry-program.zh) ## 什么是重试？ [#什么是重试] 当客户在您的店铺尝试用卡完成购买时，交易可能因多种原因被拒绝。之后使用同一张卡再次尝试完成该交易的行为称为重试。 卡支付购买交易（有卡或无卡）以及 Zero Auth（卡片验证）交易均须遵守卡组织的重试规则。 ### 各卡组织的费用与限制 [#各卡组织的费用与限制] 每个卡组织都为重试设定了具体的费用标准，开始收费前允许的尝试次数也因卡组织而异。 ### 有卡与无卡交易 [#有卡与无卡交易] 卡组织为有卡交易和无卡交易（例如线上销售）分别制定了不同的规则。 ### 超限的处罚 [#超限的处罚] 不遵守重试规则的电商，可能会按各卡组织的计划，就超限交易被收取额外费用。 ## 可逆与不可逆拒绝 [#可逆与不可逆拒绝] 为改善购买体验，支付行业与 ABECS 合作，对卡交易被拒时的响应代码进行了标准化。重试被划分为两种类型：不可逆和可逆。 **不可逆：绝不允许重试** 这类拒绝表示卡片已注销、丢失或被盗，存在已确认的欺诈，或该特定产品不允许此类交易。在上述任一情况下，发卡行都绝不会批准。如果在不可逆拒绝之后，未更改请求中的任何数据就再次发起授权尝试，交易将继续被拒绝。 **可逆：允许重试** 此时发卡行最终可能会批准交易，只是由于系统故障、可用额度不足、疑似欺诈或密码输错次数过多等临时问题，当下未予批准。这类拒绝是暂时性的，可能随时间改变，新的尝试有机会获批。 Visa、Mastercard 和 Elo 三家卡组织已调整规则，以限制被拒交易的授权尝试次数。这些变化规定，当尝试次数超出允许上限时将收取费用。以下是各卡组织的具体规则。 ## Mastercard [#mastercard] Mastercard 卡组织设有 Transaction Processing Excellence（TPE）计划，包含两个类别： 1. Excessive Attempts：监控有卡和无卡环境中被拒交易的重试，对可逆和不可逆拒绝代码均有效。 2. Merchant Advice Code Transaction Excellence（MAC）：监控无卡环境中不可逆被拒交易的重试。仅 MAC 03 和 21 会产生收费。 ### Excessive Attempts [#excessive-attempts] 当商户超出交易重试规则时收取的费用。 卡组织还会监控任何已获批的名义金额授权，即金额低于 1 个完整货币单位（或等值 1 美元）、获批后随即退款的交易。 监控适用于在有卡和无卡环境中进行的被拒及获批购买交易的重试。 Excessive Attempts 表： | 类别 | 代码 | 生效期 | 境内费用 | 跨境费用 | 何时发生 | 是否允许重试 | | --------- | --------------------------------------------------------------- | ---------------- | ------- | ---- | ---------- | ------------- | | 有卡交易和无卡交易 | 未归入 MAC 03 和 21 的任何拒绝代码；如未遵守“Excessive Attempts”的限制，也包括各 MAC 代码 | 至 31/01/2023 | R$ 2,00 | \* | 自第 11 次重试起 | 允许在 24 小时后重试。 | | 有卡交易和无卡交易 | 未归入 MAC 03 和 21 的任何拒绝代码；如未遵守“Excessive Attempts”的限制，也包括各 MAC 代码 | 自 01/02/2023 起生效 | R$ 2,00 | \* | 自第 8 次重试起 | 允许在 24 小时后重试。 | * 在同一张卡和同一商户编号上的所有支付交易均计为重试； * Mastercard 已将该计划（Excessive Attempts）新规则的生效日期从原定的 01/11/2022 推迟至 01/02/2023。变化如下： 1. 计划中的超限从核算月内的第八次重试开始计算；收费金额有所调整。 2. Mastercard 还引入了在连续 30 天内、同一张卡和同一商户编号最多 35 次被拒尝试的上限。即使店铺未超过 24 小时内 7 次重试的限制，但超出了月度上限，仍会被收费。 Excessive Attempts 计划的现行规则自 01/02/2023 起生效（见 Excessive Attempts 表）：对同一笔交易（同一张卡、同一商户编号），自第 8 次重试起收费，且允许在 24 小时后重试。截至 31/01/2023 适用的是此前的规则，在收费前允许 10 次尝试。 ### Merchant Advice Code Transaction Excellence（MAC） [#merchant-advice-code-transaction-excellencemac] 当商户针对不可逆响应代码、使用同一张卡重试发送授权时收取的费用，适用于无卡交易。 在该重试计划内，有专门针对“请勿再次尝试此交易”场景的子计划。对于这些情况，Mastercard 会用 MAC 03 和 MAC 21 等取值来标识交易。 MAC 计划包含多个取值，但只有 MAC 03 和 21 有专门的收费，其余 MAC 不在此收费范围内。 其他 MAC 代码（01、02、04、24、25、26、27、28、29、30、40 和 41）不计入 MAC 收费计划，但若超出限制，则计入 Excessive Attempts 计划的收费。 自 14/10/2022 起，当发卡行以响应代码 51（余额不足）拒绝交易并附带下表中的某个 MAC 时，Mastercard 引入了新的 MAC 代码（24、25、26、27、28、29 和 30），以便商户采取最合适的行动。 完整 MAC 对照表： | MAC | 描述 | 备注 | | --- | ----------------------- | -------------------------------------- | | 01 | 新账户信息可用（ABU） | 需要更新交易所用账户的数据，例如使用 ABU。 | | 02 | 目前无法批准，请稍后重试 | 请在 72 小时后重试该交易，或改用其他支付方式。 | | 03 | 不允许重试 | 请寻找其他方式确保收款，避免多次授权请求持续被拒带来的不必要成本。 | | 04 | 该 token 模式的 token 要求未满足 | 需要检查 token 要求，因为交易中发送的该 token 模式未满足要求。 | | 21 | 计划已取消 | 买家已取消计划，但商户在取消后仍继续发送购买授权请求。 | | 24 | 请在 1 小时后重试 | 仅对响应代码 51（余额不足）有效。 | | 25 | 请在 24 小时后重试 | 仅对响应代码 51（余额不足）有效。 | | 26 | 请在 2 天后重试 | 仅对响应代码 51（余额不足）有效。 | | 27 | 请在 4 天后重试 | 仅对响应代码 51（余额不足）有效。 | | 28 | 请在 6 天后重试 | 仅对响应代码 51（余额不足）有效。 | | 29 | 请在 8 天后重试 | 仅对响应代码 51（余额不足）有效。 | | 30 | 请在 10 天后重试 | 仅对响应代码 51（余额不足）有效。 | | 40 | 不允许重试 | 不可充值的预付消费卡。 | | 41 | 不允许重试 | 消费者一次性使用的虚拟卡。 | 此外，以下部分返回代码将不再发送： * 04（没收卡） * 14（卡号无效） * 43（被盗卡） * 54（卡片过期） * 57（交易不允许） * 62（受限卡） * 63（安全违规） **Mastercard 返回代码归类** 对于发卡行的一些往往无法告知商户能否重试的响应代码，Mastercard 可能将其合并为三个 Mastercard 专用代码： * 79（生命周期）； * 82（政策）； * 83（欺诈/安全）。 原始代码将被 Merchant Advice Code（MAC）取代，MAC 会与代码 79、82 和 83 一同出现，用于判定交易能否重试。 例如： | 当 | 则 | 响应代码 | | ---------------------- | ------------------------------------ | ------------------------------- | | 发卡行使用响应代码 54（卡片过期）拒绝交易 | Mastercard 会将代码 54 替换为代码 79（因生命周期拒绝） | 附带相应的 Merchant Advice Code（MAC） | **MAC 03 和 MAC 21 重试计划** 核算方式： * 仅考虑无卡交易； * 在同一张卡和同一商户编号上的所有支付交易均计为重试； * 计入 MAC 计划中取值为 MAC 03 和 MAC 21 的重试； * 对任何响应代码均有效； * 计划中的超限从核算月内的第 1 次重试开始计算； * 计数器在 30 天周期后清零； * 若超出各自计划的限制，重试可能同时在 MAC 03/21 和 Excessive Attempts 中被收费； * 此前适用的费用为 R$ 1,25；自 2023 年 1 月 1 日起，改为下表所列金额。 费用表： | 重试次数 | 规则 | | --------- | ----------------------------------- | | 自第 1 次重试起 | 自第 1 次重试起，每次重试收取 R$ 2,50（2.50 雷亚尔）。 | ## Visa [#visa] Visa 卡组织设立的重试计划在商户超出重试规则时产生收费。 其目的是在交易生态中建立平衡，确保收单机构和商户提供准确的重试信息，并减少不必要的再次尝试。 该卡组织要求发卡行使用正确而非泛化的响应代码，以便识别交易被拒的原因。 Visa 将这些代码分为可逆和不可逆两类，对有卡和无卡交易均有效： * 可逆代码：同一笔交易（同一张卡、交易、有效期、金额和商户）在 30 天内最多允许 20 次批准尝试。自首次尝试起满 30 天后，任何重试都将被收费。30 天期限过后，一旦发送同一交易的重试，即会被收费。此时 20 次尝试的规则不再适用，改为以 30 个自然日为准。 * 不可逆代码：同一笔交易（同一张卡、交易、有效期、金额和商户）仅允许第 1 次批准尝试。第二次尝试即会被收费，无论在何时进行。 费用：超出卡组织设定的尝试上限后，每笔超限交易都会被收取费用。 * 境内：USD 0.10 + 13.83% 的税费； * 境外：USD 0.25 + 13.83% 的税费。 该费用自 2021 年 4 月起开始收取。 Visa 将返回代码分为四个类别： * **类别 1：发卡行绝不批准。** 表示卡片已注销或从未存在，或该拒绝源于永久性限制或错误条件，未来也不会获批。 * **类别 2：发卡行目前无法批准。** 表示该拒绝源于临时状况，例如信用风险、发卡行的频率控制或其他可能允许重试获批的卡片限制。在某些情况下，需要持卡人或发卡行采取行动解除限制后才能获批。 * **类别 3：数据质量。** 当发卡行识别出数据错误时，交易会因此被拒。商户在重试前应重新校验支付数据。商户和收单机构应监控这些拒绝代码，因为存在潜在的欺诈风险。注意：类别 3 除类别 2 的限制外，还有一个累计计算的独立上限。一个商户在 30 天内最多可进行 25,000 笔交易（此处仅按商户编号和拒绝代码计算）。超出上限后，所有类别 3 的被拒交易都将被收费。 * **类别 4：泛化响应代码。** 类别 4 包括未列入类别 1、2、3 的所有其他拒绝响应代码，因为在某些情况下，特定拒绝状况可能没有对应的响应代码值。发卡行可以使用 VisaNet 技术规范中定义的其他响应代码值，但应尽量少用。 发卡行应使用能更准确反映拒绝原因的响应代码，即聚焦于类别 1（发卡行绝不批准）、类别 2（发卡行目前无法批准）和类别 3（数据质量），避免使用类别 4（泛化响应代码）。发卡行应最大限度地限制该类别的使用。收取类别 4 费用的目的，是确保发卡行归入类别 4 的拒绝占其全部拒绝的比例不超过区域核定的百分比。超出区域设定上限的发卡行，将按交易对每笔超出上限的拒绝被收取泛化响应代码费用。 规则与拒绝代码表。下表规则对购买交易和 Zero Auth 交易均有效： | 类别 | 类型 | 代码 | 规则 | | -------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 类别 1
发卡行不会批准新的尝试 | 不可逆 | 04 - 没收卡
07 - 没收卡，特殊情况
12 - 无效交易
14\* - 无效账号
15 - 发卡行不存在
41 - 没收卡（卡片丢失）
43 - 没收卡（卡片被盗）
46 - 账户已注销
57 - 持卡人不允许进行该交易
R0 - 停止付款指令
R1 - 撤销授权指令
R3 - 撤销全部授权指令 | 自第 2 次尝试起收取费用。 | | 类别 2
发卡行目前不会批准；允许新的尝试 | 可逆 | 03 - 无效商户
19 - 重新录入交易
39\*\* - 无信用账户
51 - 余额不足
52\*\* - 无活期账户
53\*\* - 无储蓄账户
59 - 疑似欺诈
61 - 超出取款金额限制
62 - 受限卡（卡片在该地区或国家无效）
65 - 超出取款频率
75 - 超出允许的密码输入尝试次数
78 - 已冻结、首次使用或特殊情况（账户暂时被冻结）
86 - ATM 故障
91 - 发卡行或转接系统不可用
93 - 交易无法完成（违反法律）
96 - 系统故障
N3 - 取款服务不可用
N4 - 取现请求超出发卡行限额
Z5\*\*\* - 账户有效，但金额不受支持
5C\*\*\*\* - 交易不受支持/被发卡行拦截
9G\*\*\*\* - 被持卡人拦截（请联系持卡人）。 | 自第 16 次尝试起收取费用：商户可对同一笔交易重试 15 次。
自首次尝试起 30 个自然日内，从第 16 次尝试（同一张卡、交易、有效期、金额和商户）起，交易将被收费。30 天期限过后，Visa 不再允许任何新的尝试。因此，若再发送该笔交易的尝试，该次重试即会被收费（此时 15 次尝试的规则不再适用，改为以 30 个自然日为准）。 | | 类别 3
数据质量 | 可逆 | 54 - 卡片过期
55 - 密码错误
70 - 需要 PIN 数据（仅限欧洲地区）
82 - CAM、dCVV、iCVV 或在线 CVV 校验结果为否
1A - 需要额外的客户认证（仅限欧洲地区）
6P - 校验失败（持卡人身份与发卡行记录不符）
N7 - 因 CVV2 校验失败而拒绝（Visa） | 自第 16 次尝试起收取费用：商户可对同一笔交易重试 15 次。
自首次尝试起 30 个自然日内，从第 16 次尝试（同一张卡、交易、有效期、金额和商户）起，交易将被收费。30 天期限过后，Visa 不再允许任何新的尝试。因此，若再发送该笔交易的尝试，该次重试即会被收费（此时 15 次尝试的规则不再适用，改为以 30 个自然日为准）。 | | 类别 4
泛化响应代码 | 可逆 | 未列入类别 1、2、3 的泛化响应代码 | 自第 16 次尝试起收取费用：商户可对同一笔交易重试 15 次。
自首次尝试起 30 个自然日内，从第 16 次尝试（同一张卡、交易、有效期、金额和商户）起，交易将被收费。30 天期限过后，Visa 不再允许任何新的尝试。因此，若再发送该笔交易的尝试，该次重试即会被收费（此时 15 次尝试的规则不再适用，改为以 30 个自然日为准）。 | 自 2023 年 4 月起，类别 3 拒绝总数的允许上限在 30 天的账单周期内由 10,000 次提高到 25,000 次。 ## Elo [#elo] 以下规则已于 2025 年 1 月生效。 此次变更的目的是确保商户和收单机构减少不必要的再次批准尝试。 交易按月核算，从违规当月的第 1 个自然日计至最后一个自然日。 费用如下： | 收费 | | ---------------------- | | 每次超限尝试收取 R$ 0,80（80 分） | ### 各分组的收费规则 [#各分组的收费规则] 该卡组织将按分成三个类别的分组来考量可逆和不可逆代码。以下是已生效的变更： | 分组 | 描述 | 收费 | | --- | --------------------------------------- | ---------------------------------------------------------------- | | 组 1 | 使用不可逆代码被拒的无卡交易，按同一卡号、同一商户 CNPJ 和同一金额计算。 | 自核算月内第 2 次重试起收费。 | | 组 2 | 使用可逆代码被拒的无卡交易。 | 自核算月内第 16 次重试起收费。 | | 组 3 | 具有暴力破解攻击特征的被拒无卡交易，按同一商户根 CNPJ 计算。 | 自第 10,001 笔被拒交易起（在该代码类别内）且超出全部拒绝的 5% 时收费，具体取决于所涉无卡交易（CNP）的支付交易量。 | 分组分类： | 组 1
发卡行绝不批准（不可逆） | 组 2
发卡行目前无法批准（可逆） | 组 3
数据质量，请重新校验信息（\*） | | --------------------- | -------------------------------- | ------------------------- | | 57 - 不允许 | 51 - 额度不足 | 54 - 卡片过期 | | 14 或 56 - 无效卡（\*） | 59 - 疑似欺诈 | 55 - 密码无效 | | 58 - 无效商户 | 04 - 重新发起交易 | 82 - 卡片密文无效 | | 46 - 账户已注销 | 06 - 请咨询收单机构 | 63 - CVE 无效或缺失 | | FM - 请使用芯片 | 38 - 超出购物密码尝试次数 | | | 19 - 请咨询收单机构 | 61 - 取款金额超限 | | | 12 - 卡片错误 | 62 - 因逾期临时冻结 | | | 30 - 报文格式错误 | 65 - 超出取款次数 | | | 13 - 交易金额无效 | 75 - 超出密码/取款尝试次数 | | | 23 - 分期金额无效 | 78 - 新卡未激活或被客户在 APP/NFC/E-COM 冻结 | | | 41 - 卡片丢失 | 91 - 发卡行系统不可用 | | | 43 - 卡片被盗 | | | | 64 - 交易最低金额无效 | | | | 83 - 密码加密错误 | | | | 76 - 目标账户无效 | | | | 77 - 来源账户无效 | | | ## 其他卡组织 [#其他卡组织] * 可逆代码：允许对同一客户和同一张卡进行新的重试，没有预先设定的次数限制和期限。重要提示：在再次尝试前，请遵循被拒交易响应中收到的指引。 * 不可逆代码：收到发卡行的第 1 次拒绝响应后，不再允许对同一张卡或商户进行授权。 ## 按返回码的重试 [#按返回码的重试] 下表列出 `returnCode` 返回的代码及其含义、建议的处理措施，以及是否允许重试。 | 响应代码 | 定义 | 含义 | 处理措施 | 是否允许重试 | | ----- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------- | | 0 | 交易授权成功。 | 交易授权成功。 | 交易授权成功。 | 否 | | 002 | 凭证无效 | PayZu 侧存在针对该终端的封锁 | 请联系 PayZu 电商支持团队 | 是 | | 2 | 交易未获授权。交易被转介。 | 交易未获授权。被发卡行转介(疑似欺诈)。 | 交易未获授权。请联系您的发卡行。 | 否 | | 9 | 交易部分撤销成功。 | 交易部分撤销成功 | 交易部分撤销成功 | 否 | | 11 | 境外发行卡交易授权成功 | 交易授权成功。 | 交易授权成功。 | 否 | | 21 | 撤销未完成。未找到交易。 | 无法处理撤销。如错误持续,请联系 PayZu。 | 无法处理撤销。请稍后重试。如错误持续,请联系网店。 | 否 | | 22 | 分期方案无效。分期期数无效。 | 无法处理交易。分期期数无效。如错误持续,请联系 PayZu。 | 无法处理交易。金额无效。请核对所填信息后重新发起交易。如错误持续,请联系网店。 | 否 | | 24 | 分期期数无效。 | 无法处理交易。分期期数无效。如错误持续,请联系 PayZu。 | 无法处理交易。分期期数无效。请核对所填信息后重新发起交易。如错误持续,请联系网店。 | 否 | | 60 | 交易未获授权。 | 交易未获授权。请重试。如错误持续,持卡人应联系发卡行。 | 无法处理交易。请稍后重试。如错误持续,请联系您的发卡行。 | 16 天内最多 4 次。 | | 67 | 交易未获授权。卡片今日已被冻结,无法消费。 | 交易未获授权。卡片今日已被冻结,无法消费。冻结可能由无效尝试次数过多导致。卡片将在午夜自动解冻。 | 交易未获授权。卡片被临时冻结。请联系您的发卡行。 | 次日起,16 天内最多 4 次。 | | 70 | 交易未获授权。额度超限/余额不足。 | 交易未获授权。额度超限/余额不足。 | 交易未获授权。请联系您的发卡行。 | 次日起,16 天内最多 4 次。 | | 72 | 撤销未完成。可用于撤销的余额不足。 | 撤销未完成。可用于撤销的余额不足。如错误持续,请联系 PayZu。 | 撤销未完成。请稍后重试。如错误持续,请联系网店。 | 否 | | 79 | 该卡不允许此 Mastercard 交易 | 交易未获授权。因持卡人卡片相关的错误无法处理交易。请持卡人联系发卡行。 | 请联系您的银行 | 否 | | 80 | 交易未获授权。交易/付款日期不一致。 | 交易未获授权。交易日期或首次付款日期无效。 | 交易未获授权。请核对信息后重新发起交易。 | 否 | | 82 | Mastercard 交易未获授权。请致电发卡行 | 因发卡行规则交易未获授权。请引导持卡人联系发卡行。 | 请联系您的银行 | 否 | | 83 | Mastercard 交易疑似欺诈 | 交易未获授权。发卡行判定疑似欺诈。 | 请联系您的银行 | 否 | | 85 | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,可能是商户终端存在问题,此时商户应联系 PayZu。 | 交易不允许。请重新输入卡片信息。如错误持续,请联系网店。 | 否 | | 89 | 交易错误。 | 交易未获授权。交易出错。持卡人应重试;如错误持续,请联系发卡行。 | 交易未获授权。交易出错。请重试;如错误持续,请联系您的发卡行。 | 16 天内最多 4 次。 | | 90 | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,可能是商户终端存在问题,此时商户应联系 PayZu。 | 交易不允许。请重新输入卡片信息。如错误持续,请联系网店。 | 否 | | 97 | 该交易不允许此金额。 | 交易未获授权。该交易不允许此金额。 | 交易未获授权。该交易不允许此金额。 | 否 | | 98 | 系统/通讯不可用。 | 交易未获授权。发卡行系统通讯中断。如属大面积故障,请检查 SITEF、GATEWAY 和/或网络连接。 | 您的交易无法处理,请稍后重试。如错误持续,请联系网店。 | 16 天内最多 4 次。 | | 475 | 撤销超时 | 应用未在预期时间内响应。 | 请几秒后重试。如错误持续,请联系支持团队。 | 否 | | 999 | 系统/通讯不可用。 | 交易未获授权。发卡行系统通讯中断。请稍后重试。可能是 SITEF 错误,请检查! | 您的交易无法处理,请稍后重试。如错误持续,请联系网店。 | 次日起,16 天内最多 4 次。 | | AA | 超时 | 与发卡行通讯超时。请引导持卡人重试;如错误持续,持卡人需联系发卡行。 | 与发卡行通讯超时,请稍后重试。如错误持续,请联系您的银行。 | 16 天内最多 4 次。 | | AF | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,可能是商户终端存在问题,此时商户应联系 PayZu。 | 交易不允许。请重新输入卡片信息。如错误持续,请联系网店。 | 否 | | AG | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,可能是商户终端存在问题,此时商户应联系 PayZu。 | 交易不允许。请重新输入卡片信息。如错误持续,请联系网店。 | 否 | | AH | 交易不允许。信用卡被当作借记卡使用。请使用贷记功能。 | 交易不允许。信用卡被当作借记卡使用。请持卡人选择信用卡支付方式。 | 交易未获授权。请选择信用卡支付方式后重试。 | 否 | | AI | 交易未获授权。未完成身份验证。 | 交易未获授权。未完成身份验证。持卡人未完成验证流程。请持卡人核对信息后重试。如错误持续,请联系 PayZu 并提供 BIN(卡号前 6 位) | 交易未获授权。身份验证未成功完成。请重试并正确填写所需信息。如错误持续,请联系商户。 | 否 | | AJ | 交易不允许。在仅支持 Private Label 的操作中发起了信用或借记交易。请重试并选择 Private Label 选项。 | 交易不允许。在仅支持 Private Label 的操作中发起了信用或借记交易。请持卡人重试并选择 Private Label 选项。如未提供 Private Label 选项,请向 PayZu 确认您的商户是否支持该操作。 | 交易不允许。在仅支持 Private Label 的操作中发起了信用或借记交易。请重试并选择 Private Label 选项。如再次出错,请联系网店。 | 否 | | AV | 交易未获授权。数据无效 | 交易数据校验失败。请引导持卡人核对信息后重试。 | 数据校验失败。请核对所填信息后重试。 | 16 天内最多 4 次。 | | BD | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,可能是商户终端存在问题,此时商户应联系 PayZu。 | 交易不允许。请重新输入卡片信息。如错误持续,请联系网店。 | 否 | | BL | 交易未获授权。超出单日限额。 | 交易未获授权。超出单日限额。请持卡人联系发卡行。 | 交易未获授权。超出单日限额。请联系您的发卡行。 | 次日起,16 天内最多 4 次。 | | BM | 交易未获授权。卡片无效 | 交易未获授权。卡片无效。可能是卡片在发卡行被冻结或信息有误。建议使用 Luhn 算法(Mod 10)校验,以避免此类未授权交易。 | 交易未获授权。卡片无效。请核对所填信息后重新发起交易。 | 否 | | BN | 交易未获授权。卡片或账户被冻结。 | 交易未获授权。持卡人的卡片或账户已被冻结。请持卡人联系发卡行。 | 交易未获授权。持卡人的卡片或账户已被冻结。请联系您的发卡行。 | 否 | | BO | 交易不允许。操作失败。 | 交易不允许。处理过程中发生错误。请持卡人重新输入卡片信息;如错误持续,请联系发卡行。 | 交易不允许。处理过程中发生错误。请重新输入卡片信息;如错误持续,请联系发卡行。 | 16 天内最多 4 次。 | | BP | 交易未获授权。活期账户不存在。 | 交易未获授权。因持卡人卡片或账户相关的错误无法处理交易。请持卡人联系发卡行。 | 交易未获授权。因持卡人卡片或账户相关的错误无法处理交易。请联系发卡行。 | 否 | | BP171 | 因欺诈风险被拒(Velocity)。 | 与 Velocity 规则相关 | 请 1 小时后重试。 | 是 | | BP176 | 交易不允许。 | 合作伙伴应确认集成流程是否已成功完成。 | 合作伙伴应确认集成流程是否已成功完成。 | N/A | | BP900 | 操作失败。 | 与操作(请求发送流程)中的故障相关。 | 请 5 分钟后重试。建议在重新发起授权前先查询交易状态。 | 是 | | BP901 | 操作失败。 | 与授权环节的故障相关。 | 请 5 分钟后重试。建议在重新发起授权前先查询交易状态。 | 是 | | BP902 | 请等待上一操作的响应。 | 与请款(capture)环节的故障相关。 | 请重试。 | 是 | | BP903 | 撤销失败。 | 与撤销环节的故障相关。 | 请重试。 | 是 | | BP904 | 查询失败。 | 与查询环节的故障相关。 | 请重试。 | 是 | | BR | 交易未获授权。账户已销户 | 持卡人账户已销户。请持卡人联系发卡行。 | 持卡人账户已销户。请持卡人联系发卡行。 | 否 | | C1 | 交易不允许。该卡无法处理借记交易。 | 请更换支付方式或卡片。 | 请更换支付方式或卡片。 | 否 | | C2 | 交易不允许。 | 信息有误。请核对支付页面填写的信息。 | 信息有误。请核对支付页面填写的信息。 | 否 | | C3 | 交易不允许。 | 该类型交易的时段无效。 | 该类型交易的时段无效。 | 否 | | CF | 交易未获授权。数据校验失败。 | 交易未获授权。数据校验失败。请持卡人联系发卡行。 | 交易未获授权。数据校验失败。请联系发卡行。 | 否 | | CG | 交易未获授权。数据校验失败。 | 交易未获授权。数据校验失败。请持卡人联系发卡行。 | 交易未获授权。数据校验失败。请联系发卡行。 | 否 | | DF | 交易不允许。卡片故障或卡片无效。 | 交易不允许。卡片故障或卡片无效。请持卡人重新输入卡片信息;如错误持续,请联系银行 | 交易不允许。卡片故障或卡片无效。请重新输入卡片信息;如错误持续,请联系银行 | 16 天内最多 4 次。 | | DM | 交易未获授权。额度超限/余额不足。 | 交易未获授权。额度超限/余额不足。 | 交易未获授权。请联系您的发卡行。 | 次日起,16 天内最多 4 次。 | | DQ | 交易未获授权。数据校验失败。 | 交易未获授权。数据校验失败。请持卡人联系发卡行。 | 交易未获授权。数据校验失败。请联系发卡行。 | 否 | | DS | 该卡不允许此交易 | 交易未获授权。该卡不允许此交易。 | 交易未获授权。请联系您的发卡行。 | 16 天内最多 4 次。 | | EB | 分期期数超出允许范围。 | 交易未获授权。请联系 PayZu 确认账户是否已开通分期。 | 交易未获授权。请联系 PayZu 确认账户是否已开通分期。 | 是 | | EE | 交易不允许。分期金额低于允许的最低值。 | 交易不允许。分期金额低于允许的最低值。不允许低于 R$ 5,00 的分期。需要重新核算分期金额。 | 交易不允许。分期金额低于允许的最低值。请联系网店。 | 否 | | EK | 该卡不允许此交易 | 交易未获授权。该卡不允许此交易。 | 交易未获授权。请联系您的发卡行。 | 16 天内最多 4 次。 | | FC | 交易未获授权。请致电发卡行 | 交易未获授权。请引导持卡人联系发卡行。 | 交易未获授权。请联系您的发卡行。 | 否 | | FE | 交易未获授权。交易/付款日期不一致。 | 交易未获授权。交易日期或首次付款日期无效。 | 交易未获授权。请核对信息后重新发起交易。 | 否 | | FF | 撤销成功 | 撤销交易授权成功。注意:此返回码仅适用于撤销场景,不适用于授权场景。 | 撤销交易授权成功 | 否 | | FG | 交易未获授权。请致电 AmEx 08007285090。 | 交易未获授权。请引导持卡人联系 AmEx 客服中心。 | 交易未获授权。请拨打 AmEx 客服中心电话 08007285090 | 否 | | GA | 请等待联系 | 交易未获授权。被 Lynx Online 预防性转介。 | 交易未获授权。商户请等待 PayZu 主动联系 | 否 | | GF | 交易被拒。 | 交易未获授权,请确认所提供的 IP 是否已被允许处理交易 | 交易不允许。请联系 PayZu。 | 否 | | GD | 交易不允许。 | 交易不允许。请联系 PayZu。 | 交易不允许。请联系 PayZu。 | N/A | | GT | 交易被拒。 | 暴力破解攻击。 | 交易不允许。请联系 PayZu。 | 否 | | GK | 交易被拒。 | 因暴力破解攻击临时封锁。 | 交易不允许。请联系 PayZu。 | 否 | | HJ | 交易不允许。操作代码无效。 | 交易不允许。Coban 操作代码无效。 | 交易不允许。Coban 操作代码无效。请联系商户。 | 否 | | IA | 交易不允许。操作标识无效。 | 交易不允许。Coban 操作标识无效。 | 交易不允许。Coban 操作标识无效。请联系商户。 | 否 | | KA | 交易不允许。数据校验失败。 | 交易不允许。数据校验失败。请持卡人核对信息后重试。如错误持续,请检查网店与 PayZu 之间的通讯。 | 交易不允许。数据校验失败。请核对所填信息后重试。如错误持续,请联系网店。 | 否 | | KB | 交易不允许。选择了错误的选项。 | 交易不允许。选择了错误的选项。请持卡人核对信息后重试。如错误持续,应检查网店与 PayZu 之间的通讯。 | 交易不允许。选择了错误的选项。请重试。如错误持续,请联系网店。 | 否 | | KE | 交易未获授权。数据校验失败。 | 交易未获授权。数据校验失败。所选选项未启用。请检查持卡人可用的选项。 | 交易未获授权。数据校验失败。所选选项未启用。请联系网店。 | 否 | | NR | 交易不允许。 | 交易不允许。 | 交易不允许。请 30 天后重试 | 30 天后可重试。 | | RP | 交易不允许。 | 交易不允许。 | 交易不允许。请 72 小时后重试 | 72 小时后可重试。 | | SC | 交易不允许。 | 交易不允许。循环扣款服务已取消。请勿重试。 | 交易不允许。循环扣款服务已取消。请勿重试。 | 否。 | | U3 | 交易不允许。数据校验失败。 | 交易不允许。数据校验失败。请持卡人核对信息后重试。如错误持续,请检查网店与 PayZu 之间的通讯。 | 交易不允许。数据校验失败。请核对所填信息后重试。如错误持续,请联系网店。 | 否 | | 6P | 交易未获授权。数据无效 | 交易数据校验失败。请引导持卡人核对信息后重试。 | 数据校验失败。请核对所填信息后重试。 | 16 天内最多 4 次 | # Test cards (/docs/cartao/test-cards.en) Use the cards below to simulate the different outcomes of a transaction in the sandbox environment, both the standard authorization flow and the 3DS authentication scenarios. ## Test cards (simulated) [#test-cards-simulated] Each card number simulates a transaction status and returns the corresponding return code and return message: | Transaction Status | Cards | Return code | Return Message | | -------------------- | ------------------------------------------------------ | ----------- | --------------------------------- | | Authorized | 0000000000000000 / 0000000000000001 / 0000000000000004 | 6 | Operação realizada com sucesso | | Not Authorized | 0000000000000002 | 05 | Not Authorized | | Not Authorized | 0000000000000003 | 57 | Cartão Expirado | | Not Authorized | 0000000000000005 | 78 | Cartão Bloqueado | | Not Authorized | 0000000000000006 | 99 | Time Out | | Not Authorized | 0000000000000007 | 77 | Cartão Cancelado | | Not Authorized | 0000000000000008 | 70 | Problemas com o Cartão de Crédito | | Random Authorization | 0000000000000009 | 4 to 99 | Operation Successful / Time Out | These cards are examples, considering only the last digits. If the goal is to test a transaction on the Payment Gateway using a card number, we recommend using a card number generator that satisfies the Mod10 rule (Luhn Algorithm). This practice is valid for both sandbox and production environments. ## 3DS test cards [#3ds-test-cards] If you want to simulate a specific [3DS](/docs/cartao/three-d-secure) authentication scenario, you can use the test cards below in the sandbox environment. ### Test cards with challenge [#test-cards-with-challenge] | CARD | BRAND | RESULT | DESCRIPTION | | ---------------- | -------------------------------------------------- | ---------- | ----------------------------------------------------------------------- | | 4000000000001091 | | SUCCESS | Authentication with challenge and cardholder authenticated successfully | | 5200000000001096 | | SUCCESS | Authentication with challenge and cardholder authenticated successfully | | 6505050000001091 | | SUCCESS | Authentication with challenge and cardholder authenticated successfully | | 4000000000001109 | | FAILURE | Authentication with challenge and cardholder authentication failed | | 5200000000001104 | | FAILURE | Authentication with challenge and cardholder authentication failed | | 6505050000001109 | | FAILURE | Authentication with challenge and cardholder authentication failed | | 4000000000001117 | | UNENROLLED | Authentication with challenge unavailable at the moment | | 5200000000001112 | | UNENROLLED | Authentication with challenge unavailable at the moment | | 6505050000001117 | | UNENROLLED | Authentication with challenge unavailable at the moment | | 4000000000001125 | | UNENROLLED | System error during the authentication step | | 5200000000001120 | | UNENROLLED | System error during the authentication step | | 6505050000001125 | | UNENROLLED | System error during the authentication step | ### Test cards without challenge [#test-cards-without-challenge] | CARD | BRAND | RESULT | DESCRIPTION | | ---------------- | -------------------------------------------------- | ---------- | -------------------------------------------------------------------------- | | 4000000000001000 | | SUCCESS | Authentication without challenge and cardholder authenticated successfully | | 5200000000001005 | | SUCCESS | Authentication without challenge and cardholder authenticated successfully | | 6505050000001000 | | SUCCESS | Authentication without challenge and cardholder authenticated successfully | | 4000000000001000 | | UNENROLLED | Authentication without challenge and cardholder authentication failed | | 5200000000001005 | | UNENROLLED | Authentication without challenge and cardholder authentication failed | | 6505050000001000 | | UNENROLLED | Authentication without challenge and cardholder authentication failed | The numbers above reproduce the official PayZu reference exactly. In the no-challenge table, the reference itself lists the same cards for the success and the failure scenarios. Before automating tests for these scenarios, confirm with support which number to use for each one. ## Next steps [#next-steps] # Cartões de teste (/docs/cartao/test-cards) Use os cartões abaixo para simular os diferentes resultados de uma transação no ambiente de sandbox, tanto o fluxo padrão de autorização quanto os cenários de autenticação 3DS. ## Cartões de teste (simulado) [#cartões-de-teste-simulado] Cada número de cartão simula um status de transação e devolve o código e a mensagem de retorno correspondentes: | Status da Transação | Cartões | Código de retorno | Mensagem de Retorno | | --------------------- | ------------------------------------------------------ | ----------------- | --------------------------------- | | Autorizado | 0000000000000000 / 0000000000000001 / 0000000000000004 | 6 | Operação realizada com sucesso | | Não Autorizado | 0000000000000002 | 05 | Não Autorizada | | Não Autorizado | 0000000000000003 | 57 | Cartão Expirado | | Não Autorizado | 0000000000000005 | 78 | Cartão Bloqueado | | Não Autorizado | 0000000000000006 | 99 | Time Out | | Não Autorizado | 0000000000000007 | 77 | Cartão Cancelado | | Não Autorizado | 0000000000000008 | 70 | Problemas com o Cartão de Crédito | | Autorização Aleatória | 0000000000000009 | 4 a 99 | Operation Successful / Time Out | Estes cartões são exemplos, considerando apenas os últimos dígitos. Caso o objetivo seja testar uma transação no Gateway de Pagamento utilizando um número de cartão, é recomendado o uso de um gerador de números de cartão que atenda à regra do Mod10 (Algoritmo de Luhn). Essa prática é válida tanto para ambientes sandbox quanto para ambientes de produção. ## Cartões de teste 3DS [#cartões-de-teste-3ds] Caso queira simular determinado cenário de autenticação [3DS](/docs/cartao/three-d-secure), você pode utilizar os cartões de teste abaixo no ambiente de sandbox. ### Cartões de teste com desafio [#cartões-de-teste-com-desafio] | CARTÃO | BANDEIRA | RESULTADO | DESCRIÇÃO | | ---------------- | -------------------------------------------------- | ---------- | ---------------------------------------------------------- | | 4000000000001091 | | SUCCESS | Autenticação com desafio e portador autenticou com sucesso | | 5200000000001096 | | SUCCESS | Autenticação com desafio e portador autenticou com sucesso | | 6505050000001091 | | SUCCESS | Autenticação com desafio e portador autenticou com sucesso | | 4000000000001109 | | FAILURE | Autenticação com desafio e portador autenticou com falha | | 5200000000001104 | | FAILURE | Autenticação com desafio e portador autenticou com falha | | 6505050000001109 | | FAILURE | Autenticação com desafio e portador autenticou com falha | | 4000000000001117 | | UNENROLLED | Autenticação com desafio indisponível no momento | | 5200000000001112 | | UNENROLLED | Autenticação com desafio indisponível no momento | | 6505050000001117 | | UNENROLLED | Autenticação com desafio indisponível no momento | | 4000000000001125 | | UNENROLLED | Erro de sistema durante a etapa de autenticação | | 5200000000001120 | | UNENROLLED | Erro de sistema durante a etapa de autenticação | | 6505050000001125 | | UNENROLLED | Erro de sistema durante a etapa de autenticação | ### Cartões de teste sem desafio [#cartões-de-teste-sem-desafio] | CARTÃO | BANDEIRA | RESULTADO | DESCRIÇÃO | | ---------------- | -------------------------------------------------- | ---------- | ---------------------------------------------------------- | | 4000000000001000 | | SUCCESS | Autenticação sem desafio e portador autenticou com sucesso | | 5200000000001005 | | SUCCESS | Autenticação sem desafio e portador autenticou com sucesso | | 6505050000001000 | | SUCCESS | Autenticação sem desafio e portador autenticou com sucesso | | 4000000000001000 | | UNENROLLED | Autenticação sem desafio e portador autenticou com falha | | 5200000000001005 | | UNENROLLED | Autenticação sem desafio e portador autenticou com falha | | 6505050000001000 | | UNENROLLED | Autenticação sem desafio e portador autenticou com falha | Os números acima reproduzem exatamente a referência oficial da PayZu. Na tabela sem desafio, a própria referência lista os mesmos cartões para o cenário de sucesso e o de falha. Antes de automatizar testes desses cenários, confirme com o suporte qual número usar para cada um. ## Próximos passos [#próximos-passos] # 测试卡 (/docs/cartao/test-cards.zh) 使用下面的卡号在 sandbox 环境中模拟交易的各种结果,既包括标准授权流程,也包括 3DS 认证场景。 ## 测试卡(模拟) [#测试卡模拟] 每个卡号模拟一种交易状态,并返回对应的返回码和返回消息: | 交易状态 | 卡号 | 返回码 | 返回消息 | | ---- | ------------------------------------------------------ | ------ | --------------------------------- | | 已授权 | 0000000000000000 / 0000000000000001 / 0000000000000004 | 6 | Operação realizada com sucesso | | 未授权 | 0000000000000002 | 05 | 未授权 | | 未授权 | 0000000000000003 | 57 | Cartão Expirado | | 未授权 | 0000000000000005 | 78 | Cartão Bloqueado | | 未授权 | 0000000000000006 | 99 | Time Out | | 未授权 | 0000000000000007 | 77 | Cartão Cancelado | | 未授权 | 0000000000000008 | 70 | Problemas com o Cartão de Crédito | | 随机授权 | 0000000000000009 | 4 至 99 | Operation Successful / Time Out | 这些卡号仅为示例,只考虑末尾几位数字。 如需使用某个卡号在支付网关中测试交易,建议使用符合 Mod10 规则(Luhn 算法)的卡号生成器。这一做法同时适用于 sandbox 环境和生产环境。 ## 3DS 测试卡 [#3ds-测试卡] 如需模拟特定的 [3DS](/docs/cartao/three-d-secure) 认证场景,可以在 sandbox 环境中使用下面的测试卡。 ### 有挑战的测试卡 [#有挑战的测试卡] | 卡号 | 卡组织 | 结果 | 描述 | | ---------------- | -------------------------------------------------- | ---------- | -------------- | | 4000000000001091 | | SUCCESS | 有挑战的认证,持卡人认证成功 | | 5200000000001096 | | SUCCESS | 有挑战的认证,持卡人认证成功 | | 6505050000001091 | | SUCCESS | 有挑战的认证,持卡人认证成功 | | 4000000000001109 | | FAILURE | 有挑战的认证,持卡人认证失败 | | 5200000000001104 | | FAILURE | 有挑战的认证,持卡人认证失败 | | 6505050000001109 | | FAILURE | 有挑战的认证,持卡人认证失败 | | 4000000000001117 | | UNENROLLED | 有挑战的认证当前不可用 | | 5200000000001112 | | UNENROLLED | 有挑战的认证当前不可用 | | 6505050000001117 | | UNENROLLED | 有挑战的认证当前不可用 | | 4000000000001125 | | UNENROLLED | 认证环节发生系统错误 | | 5200000000001120 | | UNENROLLED | 认证环节发生系统错误 | | 6505050000001125 | | UNENROLLED | 认证环节发生系统错误 | ### 无挑战的测试卡 [#无挑战的测试卡] | 卡号 | 卡组织 | 结果 | 描述 | | ---------------- | -------------------------------------------------- | ---------- | -------------- | | 4000000000001000 | | SUCCESS | 无挑战的认证,持卡人认证成功 | | 5200000000001005 | | SUCCESS | 无挑战的认证,持卡人认证成功 | | 6505050000001000 | | SUCCESS | 无挑战的认证,持卡人认证成功 | | 4000000000001000 | | UNENROLLED | 无挑战的认证,持卡人认证失败 | | 5200000000001005 | | UNENROLLED | 无挑战的认证,持卡人认证失败 | | 6505050000001000 | | UNENROLLED | 无挑战的认证,持卡人认证失败 | 以上卡号与 PayZu 官方参考完全一致。在无挑战场景的表格中,官方参考本身为成功和失败场景列出了相同的卡号。在为这些场景编写自动化测试前,请先与支持团队确认各场景应使用的卡号。 ## 后续步骤 [#后续步骤] # 3-D Secure (3DS) (/docs/cartao/three-d-secure.en) **3DS** confirms with the issuing bank that the person paying really is the cardholder. Authenticating the transaction reduces fraud and, when authentication completes successfully, shifts chargeback liability to the issuer or the card brand. During the 3DS authentication process, buyer information is shared with the card networks and the issuing bank, which assess the transaction risk and decide whether a **challenge** (such as an SMS code or authentication in the bank's app) is required to validate the cardholder's identity. ### Benefits [#benefits] * Fraud reduction * **Liability shift** on authenticated transactions: the issuer or the card network takes responsibility in case of chargeback * Simple integration via JavaScript * Support for **frictionless** authentication (no visible challenge for the buyer) when the transaction risk is considered low ## Authentication flow [#authentication-flow] When the transaction is authorized with the variables returned in the `success` event, liability shifts to the card issuer. In every other scenario, liability stays with the merchant. ## Step-by-step integration [#step-by-step-integration] ### Initialize the script [#initialize-the-script] Include the following script in your web page to load the script responsible for communicating with the card networks and the issuing banks: ```html ``` After loading the script on your page, you must initialize it as follows: ```javascript const config = { amount: 350, currency: 'BRL', options: { enabled: true, sandbox: true, debug: true, suppressChallenge: false } }; payzu3DS.init(config); ``` | Parameter | Description | Type | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `amount` | Total transaction amount in cents | integer | | `currency` | Currency code | Fixed as "BRL" | | `options.enabled` | Defines whether the transaction will be submitted to the 3DS authentication process | boolean | | `options.sandbox` | Defines whether the execution environment will be sandbox or production | boolean | | `options.debug` | When enabled, logs and reports will be emitted to the browser console | boolean | | `options.suppressChallenge` | Determines whether the challenge will be suppressed. If the challenge is skipped and the transaction is authorized, liability stays with the merchant | boolean | ### Register the authentication events [#register-the-authentication-events] Register the event listeners to handle each possible authentication result: ```javascript payzu3DS.on("ready", function (e) { }); ``` #### ready [#ready] This event fires when all script loading procedures have completed successfully, including the access token validation. It indicates that the checkout is ready to start the authentication process. #### Authentication results [#authentication-results] The liability shift happens only when authentication completes successfully: in that case, chargeback liability shifts to the issuer or the card network. In every other scenario, liability stays with the merchant. | Event | Scenario and return | Liability | Recommended action | | ------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- | | `success` | Card eligible and authentication completed successfully. Returns `Cavv`, `Xid` and `Eci`. | Shifts to the issuer | Include `Cavv`, `Xid` and `Eci` in the authorization request. | | `failure` | Card eligible, but authentication failed. Returns only `Eci`. | Stays with the merchant | If you decide to proceed with the authorization, include `Eci` in the request. | | `unenrolled` | Card not eligible: the cardholder and/or the issuer do not participate in the 3DS program. Returns only `Eci`. | Stays with the merchant | Advise the buyer to check with the issuer whether the card is enabled for e-commerce authentication. | | `disabled` | Merchant chose not to authenticate, with `options.enabled` set to `false`. | Stays with the merchant | - | | `error` | Systemic error in the authentication process. | Stays with the merchant | - | #### unsupportedBrand [#unsupportedbrand] This event fires when the card network of the card being used is not compatible with the 3DS protocol. In this case, authentication is not performed. #### Returned attributes [#returned-attributes] | Attribute | Description | Type | Required? | | --------------- | ------------------------------------------------- | ------------------------------------- | --------- | | `Cavv` | Data that represents the authentication signature | string | Yes | | `Xid` | Identifier of the authentication transaction | string | No | | `Eci` | Code that represents the authentication result | [ECI table](#eci-table) | Yes | | `Version` | Version of the 3DS protocol used | string | Yes | | `ReferenceId` | Identifier of the authentication request | string | Yes | | `ReturnCode` | Authentication return code | [3DS return codes](#3ds-return-codes) | Yes | | `ReturnMessage` | Authentication return message | [3DS return codes](#3ds-return-codes) | Yes | ### Request the challenge [#request-the-challenge] Instantiate the `paymentObject`, paying attention to the fields that are strictly required in the table below. When the checkout runs, the authentication process starts and its result is returned through the events. ```javascript const paymentObject = { installments: '01', cardnumber: '4000000000001091', cardexpirationmonth: '01', cardexpirationyear: '2027', cardalias: 'JOAO SOUZA', paymentmethod: 'Credit' } payzu3DS.checkout(paymentObject) ``` If authentication completes successfully, the `success` event fires. In that case, the `Cavv`, `Xid` and `Eci` variables are returned: they must be sent to your backend and later included in the request at authorization time. In this case, the liability shift goes to the issuer. | Attribute name | Description | Type | Length | Required | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------ | -------- | | `installments` | Number of installments of the transaction | number | 2 | Yes | | `cardnumber` | Card number | number | 19 | Yes | | `cardexpirationmonth` | Card expiration month | number | 2 | Yes | | `cardexpirationyear` | Card expiration year | number | 4 | Yes | | `cardalias` | Cardholder name printed on the card | string | 128 | No | | `paymentmethod` | Type of card to be authenticated. For a multi-function card, one of the types must be specified, Credit or Debit | Credit: credit card. Debit: debit card | 6 | Yes | | `default_card` | Indicates whether it is the customer's default card in the store | boolean | - | No | | `recurring_enddate` | Identifies the recurrence end date | string (YYYY-MM-DD) | 10 | No | | `recurring_frequency` | Indicates the recurrence frequency | number: 1 = Monthly, 2 = Bimonthly, 3 = Quarterly, 4 = Every four months, 6 = Semiannual, 12 = Annual | - | No | | `recurring_originalpurchasedate` | Date of the first transaction that originated the recurrence | string (YYYY-MM-DD) | 10 | No | | `order_recurrence` | Indicates whether it is an order that generates future recurrences | boolean | - | No | | `order_productcode` | Purchase type (PHY, CHA, ACF, QCT, PAL) | string | - | Yes | | `order_countlast24hours` | Orders placed in the last 24h | number | 3 | No | | `order_countlast6months` | Orders placed in the last 6 months | number | 4 | No | | `order_countlast1year` | Orders placed in the last year | number | 3 | No | | `order_cardattemptslast24hours` | Transactions with the same card in the last 24h | number | 3 | No | | `order_marketingoptin` | Opted in to receive marketing offers | boolean | - | No | | `order_marketingsource` | Source of the marketing campaign | string | 40 | No | | `billto_customerid` | Buyer's CPF/CNPJ | string | 11-14 | No | | `billto_contactname` | Billing address contact name | string | 120 | Yes | | `billTo_phonenumber` | Billing address phone number | string | 15 | Yes | | `billTo_email` | Billing address email | string | 255 | Yes | | `billTo_street1` | Billing address street and number | string | 60 | Yes | | `billTo_street2` | Billing address complement and district | string | 60 | Yes | | `billTo_city` | Billing address city | string | 50 | Yes | | `billTo_state` | Billing address state abbreviation | string | 2 | Yes | | `billto_zipcode` | Billing address postal code | string | 8 | Yes | | `billto_country` | Billing address country | string Ex: BR | 2 | Yes | | `shipto_sameasbillto` | Billing and shipping address are the same | boolean | - | No | | `shipto_addressee` | Shipping address contact name | string | 60 | No | | `shipTo_phonenumber` | Shipping address phone number | string | 15 | No | | `shipTo_email` | Shipping address email | string | 255 | No | | `shipTo_street1` | Shipping address street and number | string | 60 | No | | `shipTo_street2` | Shipping address complement and district | string | 60 | No | | `shipTo_city` | Shipping address city | string | 50 | No | | `shipTo_state` | Shipping address state abbreviation | string | 2 | No | | `shipto_zipcode` | Shipping address postal code | string | 8 | No | | `shipto_country` | Shipping address country | string Ex: BR | 2 | No | | `shipTo_shippingmethod` | Shipping method type (lowcost, sameday, oneday, twoday, etc.) | string | - | No | | `shipto_firstusagedate` | Date the shipping address was first used | string (YYYY-MM-DD) | 10 | No | The Type column reproduces the source documentation. In the official example above, `installments`, `cardnumber`, `cardexpirationmonth` and `cardexpirationyear` are sent as strings; follow the example, especially for `cardnumber`, to avoid numeric precision loss. ### Use the result in the charge [#use-the-result-in-the-charge] To create a charge using 3DS, you must set the `authenticate` field to `true` and provide the `externalAuthentication` field inside `creditCardPayment`: ```json { "creditCardPayment": { "authenticate": true, "externalAuthentication": { "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5", "xid": "198b924ea7db1014b64c8b426a0e6f1e", "eci": "05", "version": "2.2", "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst" } } } ``` See [Create charge](/docs/cartao/endpoints/charges/post_charges) for the remaining request fields. ## Return codes and ECI [#return-codes-and-eci] ### 3DS return codes [#3ds-return-codes] Codes returned in the 3DS authentication flow. | 3DS code | Description | Possible action | | -------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `100` | Transaction completed successfully. | - | | `101` | One or more required fields are missing from the request. | Check the fields `missingField_0` through `missingField_N` in the response. Send the request again. | | `102` | One or more request fields contain invalid data. | Check the fields `invalidField_0` through `invalidField_N` in the response. Resend the request. | | `150` | Error: general system failure. | Wait a few minutes and send the request again. | | `151` | Error: the request was received, but the server timed out. | Wait a few minutes and send the request again. | | `152` | Error: the request was received, but a service timed out. | Wait a few minutes and send the request again. | | `234` | There is a problem with your merchant configuration. | Do not send the request again. Contact support. | | `475` | The customer is enrolled in payer authentication. | Authenticate the cardholder before proceeding with the transaction. | | `476` | The customer cannot be authenticated. | Review the customer's order. | | `MPI901` | Unexpected error. | - | | `MPI902` | Unexpected authentication response. | - | | `MPI900` | An error occurred. | - | | `MPI601` | Challenge skipped. | - | | `MPI600` | Brand does not support authentication. | - | ### ECI table [#eci-table] The ECI table indicates, per brand, the authentication result and who bears the chargeback risk: | Mastercard | Visa | Elo | Amex | Authentication result | Was the transaction authenticated? | | ------------------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------- | | `02` | `05` | `05` | `05` | Authenticated by the issuer: chargeback risk shifts to the issuer. | Yes | | `01` | `06` | `06` | `06` | Authenticated by the brand: chargeback risk shifts to the issuer. | Yes | | Other than `01`, `02` and `04` | Other than `05` and `06` | Other than `05` and `06` | Other than `05` and `06` | Not authenticated: chargeback risk stays with the merchant. | No | | `04` | `7` | - | - | Not authenticated, transaction classified as Data Only: chargeback risk stays with the merchant. | No | When the transaction is not authenticated, the chargeback risk stays with the merchant. Check the ECI values in the table above before deciding to proceed with the charge. ## References [#references] * Cards to simulate 3DS authentication scenarios in the sandbox: [Test cards](/docs/cartao/test-cards) # 3-D Secure (3DS) (/docs/cartao/three-d-secure) O **3DS** confirma junto ao banco emissor que quem está comprando é o titular do cartão. Autenticar a transação reduz fraude e, quando a autenticação conclui com sucesso, transfere a responsabilidade por chargeback para o emissor ou a bandeira. Durante o processo de autenticação 3DS, informações do comprador são compartilhadas com as bandeiras e o banco emissor, que avaliam o risco da transação e definem se é necessário um **desafio** (como um código por SMS ou autenticação no app do banco) para validar a identidade do portador. ### Vantagens [#vantagens] * Redução de fraudes * **Shift de responsabilidade (liability shift)** nas transações autenticadas: o emissor ou a bandeira assumem a responsabilidade em caso de chargeback * Integração simples via JavaScript * Suporte à autenticação **sem fricção** (sem desafio visível para o comprador), quando o risco da transação é considerado baixo ## Fluxo de autenticação [#fluxo-de-autenticação] Quando a transação é autorizada com as variáveis retornadas no evento `success`, a responsabilidade (liability) é transferida para o emissor do cartão. Nos demais cenários, a responsabilidade permanece com o estabelecimento. ## Integração passo a passo [#integração-passo-a-passo] ### Inicializar o script [#inicializar-o-script] Inclua o seguinte script em sua página web para carregar o script responsável por realizar a comunicação com as bandeiras e os bancos emissores: ```html ``` Após carregar o script em sua página, será necessário inicializá-lo da seguinte maneira: ```javascript const config = { amount: 350, currency: 'BRL', options: { enabled: true, sandbox: true, debug: true, suppressChallenge: false } }; payzu3DS.init(config); ``` | Parâmetro | Descrição | Tipo | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | | `amount` | Valor total da transação em centavos | inteiro | | `currency` | Código da moeda | Fixo em "BRL" | | `options.enabled` | Define se a transação será submetida ao processo de autenticação 3DS | boolean | | `options.sandbox` | Define se o ambiente de execução utilizado será o sandbox ou de produção | boolean | | `options.debug` | Quando ativado, logs e relatórios serão emitidos no console do navegador | boolean | | `options.suppressChallenge` | Determina se o desafio será suprimido. Caso o desafio seja ignorado e a transação autorizada, a responsabilidade (liability) permanece com o estabelecimento | boolean | ### Registrar os eventos de autenticação [#registrar-os-eventos-de-autenticação] Registre os listeners dos eventos para tratar cada resultado possível da autenticação: ```javascript payzu3DS.on("ready", function (e) { }); ``` #### ready [#ready] Este evento é acionado quando todos os procedimentos de carregamento do script foram concluídos com sucesso, incluindo a validação do token de acesso. Indica que o checkout está pronto para iniciar o processo de autenticação. #### Resultados da autenticação [#resultados-da-autenticação] O liability shift ocorre somente quando a autenticação é concluída com sucesso: nesse caso, a responsabilidade por chargeback é transferida ao emissor ou à bandeira. Em todos os demais cenários, a responsabilidade permanece com o estabelecimento. | Evento | Cenário e retorno | Liability | Ação recomendada | | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `success` | Cartão elegível e autenticação concluída com sucesso. Retorna `Cavv`, `Xid` e `Eci`. | Transferida ao emissor | Inclua `Cavv`, `Xid` e `Eci` na requisição de autorização. | | `failure` | Cartão elegível, mas a autenticação falhou. Retorna apenas `Eci`. | Permanece com o estabelecimento | Se decidir prosseguir com a autorização, inclua `Eci` na requisição. | | `unenrolled` | Cartão não elegível: o portador e/ou o emissor não participam do programa 3DS. Retorna apenas `Eci`. | Permanece com o estabelecimento | Oriente o comprador a verificar com o emissor se o cartão está habilitado para autenticação em e-commerce. | | `disabled` | Estabelecimento optou por não autenticar, com `options.enabled` como `false`. | Permanece com o estabelecimento | - | | `error` | Erro sistêmico no processo de autenticação. | Permanece com o estabelecimento | - | #### unsupportedBrand [#unsupportedbrand] Este evento é acionado quando a bandeira do cartão utilizado não é compatível com o protocolo 3DS. Nesse caso, a autenticação não é realizada. #### Atributos retornados [#atributos-retornados] | Atributo | Descrição | Tipo | Obrigatório? | | --------------- | ------------------------------------------------- | ------------------------------------------------- | ------------ | | `Cavv` | Dado que representa assinatura da autenticação | string | Sim | | `Xid` | Identificador da transação de autenticação | string | Não | | `Eci` | Código que representa o resultado da autenticação | [Tabela ECI](#tabela-eci) | Sim | | `Version` | Versão do protocolo 3DS utilizada | string | Sim | | `ReferenceId` | Identificador da requisição de autenticação | string | Sim | | `ReturnCode` | Código de retorno da autenticação | [Códigos de retorno 3DS](#códigos-de-retorno-3ds) | Sim | | `ReturnMessage` | Mensagem de retorno da autenticação | [Códigos de retorno 3DS](#códigos-de-retorno-3ds) | Sim | ### Solicitar o desafio [#solicitar-o-desafio] Instancie o objeto `paymentObject`, observando os campos que são expressamente obrigatórios na tabela abaixo. Ao executar o checkout, o processo de autenticação será iniciado e seu resultado será retornado através dos eventos. ```javascript const paymentObject = { installments: '01', cardnumber: '4000000000001091', cardexpirationmonth: '01', cardexpirationyear: '2027', cardalias: 'JOAO SOUZA', paymentmethod: 'Credit' } payzu3DS.checkout(paymentObject) ``` Caso a autenticação seja concluída com sucesso, o evento `success` será acionado. Nesse caso, as variáveis `Cavv`, `Xid` e `Eci` serão retornadas: elas devem ser enviadas ao seu backend e posteriormente incluídas na requisição no momento da autorização. Neste caso, o liability shift é transferido ao emissor. | Nome do Atributo | Descrição | Tipo | Tamanho | Obrigatório | | -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------- | ----------- | | `installments` | Número de parcelas da transação | number | 2 | Sim | | `cardnumber` | Número do Cartão | number | 19 | Sim | | `cardexpirationmonth` | Mês do vencimento do cartão | number | 2 | Sim | | `cardexpirationyear` | Ano do vencimento do cartão | number | 4 | Sim | | `cardalias` | Nome do titular impresso no cartão | string | 128 | Não | | `paymentmethod` | Tipo do cartão a ser autenticado. No caso do cartão múltiplo, deverá especificar um dos tipos, Credit ou Debit | Credit: cartão de crédito. Debit: cartão de débito | 6 | Sim | | `default_card` | Indica se é um cartão padrão do cliente na loja | boolean | - | Não | | `recurring_enddate` | Identifica a data de término da recorrência | string (AAAA-MM-DD) | 10 | Não | | `recurring_frequency` | Indica a frequência da recorrência | number: 1 = Mensal, 2 = Bimestral, 3 = Trimestral, 4 = Quadrimestral, 6 = Semestral, 12 = Anual | - | Não | | `recurring_originalpurchasedate` | Data da 1ª transação que originou a recorrência | string (AAAA-MM-DD) | 10 | Não | | `order_recurrence` | Indica se é um pedido que gera recorrências futuras | boolean | - | Não | | `order_productcode` | Tipo de compra (PHY, CHA, ACF, QCT, PAL) | string | - | Sim | | `order_countlast24hours` | Pedidos efetuados nas últimas 24h | number | 3 | Não | | `order_countlast6months` | Pedidos efetuados nos últimos 6 meses | number | 4 | Não | | `order_countlast1year` | Pedidos efetuados no último ano | number | 3 | Não | | `order_cardattemptslast24hours` | Transações com o mesmo cartão nas últimas 24h | number | 3 | Não | | `order_marketingoptin` | Aceitou receber ofertas de marketing | boolean | - | Não | | `order_marketingsource` | Origem da campanha de marketing | string | 40 | Não | | `billto_customerid` | CPF/CNPJ do comprador | string | 11-14 | Não | | `billto_contactname` | Nome do contato do endereço de cobrança | string | 120 | Sim | | `billTo_phonenumber` | Telefone do endereço de cobrança | string | 15 | Sim | | `billTo_email` | E-mail do endereço de cobrança | string | 255 | Sim | | `billTo_street1` | Logradouro e Número do endereço de cobrança | string | 60 | Sim | | `billTo_street2` | Complemento e bairro do endereço de cobrança | string | 60 | Sim | | `billTo_city` | Cidade do endereço de cobrança | string | 50 | Sim | | `billTo_state` | Sigla do estado do endereço de cobrança | string | 2 | Sim | | `billto_zipcode` | CEP do endereço de cobrança | string | 8 | Sim | | `billto_country` | País do endereço de cobrança | string Ex: BR | 2 | Sim | | `shipto_sameasbillto` | Mesmo endereço de cobrança e entrega | boolean | - | Não | | `shipto_addressee` | Nome do contato do endereço de entrega | string | 60 | Não | | `shipTo_phonenumber` | Telefone do endereço de entrega | string | 15 | Não | | `shipTo_email` | E-mail do endereço de entrega | string | 255 | Não | | `shipTo_street1` | Logradouro e Número do endereço de entrega | string | 60 | Não | | `shipTo_street2` | Complemento e bairro do endereço de entrega | string | 60 | Não | | `shipTo_city` | Cidade do endereço de entrega | string | 50 | Não | | `shipTo_state` | Sigla do estado do endereço de entrega | string | 2 | Não | | `shipto_zipcode` | CEP do endereço de entrega | string | 8 | Não | | `shipto_country` | País do endereço de entrega | string Ex: BR | 2 | Não | | `shipTo_shippingmethod` | Tipo do método de envio (lowcost, sameday, oneday, twoday, etc.) | string | - | Não | | `shipto_firstusagedate` | Data da primeira utilização do endereço de entrega | string (AAAA-MM-DD) | 10 | Não | A coluna Tipo reproduz a documentação de origem. No exemplo oficial acima, `installments`, `cardnumber`, `cardexpirationmonth` e `cardexpirationyear` são enviados como string; siga o exemplo, em especial no `cardnumber`, para evitar perda de precisão numérica. ### Utilizar o resultado na cobrança [#utilizar-o-resultado-na-cobrança] Para criar uma cobrança utilizando o 3DS, é necessário definir o campo `authenticate` como `true`, além de informar o campo `externalAuthentication` dentro de `creditCardPayment`: ```json { "creditCardPayment": { "authenticate": true, "externalAuthentication": { "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5", "xid": "198b924ea7db1014b64c8b426a0e6f1e", "eci": "05", "version": "2.2", "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst" } } } ``` Consulte [Criar cobrança](/docs/cartao/endpoints/charges/post_charges) para os demais campos da requisição. ## Códigos de retorno e ECI [#códigos-de-retorno-e-eci] ### Códigos de retorno 3DS [#códigos-de-retorno-3ds] Códigos retornados no fluxo de autenticação 3DS. | Código 3DS | Descrição | Ação possível | | ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `100` | Transação realizada com sucesso. | - | | `101` | Está faltando um ou mais campos obrigatórios na requisição. | Confira os campos `missingField_0` até `missingField_N` na resposta. Envie a requisição novamente. | | `102` | Um ou mais campos da requisição contêm dados inválidos. | Confira os campos `invalidField_0` até `invalidField_N` na resposta. Reenvie a requisição. | | `150` | Erro: falha geral no sistema. | Aguarde alguns minutos e envie a requisição novamente. | | `151` | Erro: a requisição foi recebida, mas houve time-out do servidor. | Aguarde alguns minutos e envie a requisição novamente. | | `152` | Erro: a requisição foi recebida, mas houve time-out de serviço. | Aguarde alguns minutos e envie a requisição novamente. | | `234` | Há um problema na sua configuração de merchant. | Não envie a requisição novamente. Entre em contato com o suporte. | | `475` | O cliente está registrado na autenticação do pagante. | Faça a autenticação do portador do cartão antes de prosseguir com a transação. | | `476` | O cliente não pode ser autenticado. | Revise o pedido do cliente. | | `MPI901` | Erro inesperado. | - | | `MPI902` | Resposta inesperada da autenticação. | - | | `MPI900` | Ocorreu um erro. | - | | `MPI601` | Desafio omitido. | - | | `MPI600` | Bandeira não suporta a autenticação. | - | ### Tabela ECI [#tabela-eci] A tabela ECI indica, por bandeira, o resultado da autenticação e quem assume o risco de chargeback: | Mastercard | Visa | Elo | Amex | Resultado da autenticação | A transação foi autenticada? | | ------------------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `02` | `05` | `05` | `05` | Autenticada pelo emissor: risco de chargeback passa a ser do emissor. | Sim | | `01` | `06` | `06` | `06` | Autenticada pela bandeira: risco de chargeback passa a ser do emissor. | Sim | | Diferente de `01`, `02` e `04` | Diferente de `05` e `06` | Diferente de `05` e `06` | Diferente de `05` e `06` | Não autenticada: risco de chargeback permanece com o estabelecimento. | Não | | `04` | `7` | - | - | Não autenticada, transação caracterizada como Data Only: risco de chargeback permanece com o estabelecimento. | Não | Quando a transação não é autenticada, o risco de chargeback permanece com o estabelecimento. Consulte os valores de ECI da tabela acima antes de decidir prosseguir com a cobrança. ## Referências [#referências] * Cartões para simular os cenários de autenticação 3DS no sandbox: [Cartões de teste](/docs/cartao/test-cards) # 3-D Secure (3DS) (/docs/cartao/three-d-secure.zh) **3DS** 由发卡行确认付款人确实是持卡人。经过认证的交易可以降低欺诈风险，并且在认证成功时将拒付责任转移给发卡行或卡组织。 在 3DS 认证过程中,买家的信息会共享给卡组织和发卡行,由它们评估交易风险,并决定是否需要**挑战验证**(例如短信验证码或在银行 App 内认证)来验证持卡人的身份。 ### 优势 [#优势] * 降低欺诈 * 通过认证的交易享有**责任转移 (liability shift)**:发生拒付时由发卡行或卡组织承担责任 * 通过 JavaScript 即可轻松集成 * 支持**无摩擦**认证(买家看不到任何挑战验证),适用于交易风险被判定为低的场景 ## 认证流程 [#认证流程] 当交易使用 `success` 事件返回的变量完成授权时,责任 (liability) 转移给发卡行。在其他所有场景中,责任仍由商户承担。 ## 分步集成 [#分步集成] ### 初始化脚本 [#初始化脚本] 在您的网页中引入以下脚本,它负责与卡组织和发卡行进行通信: ```html ``` 脚本加载完成后,需要按如下方式初始化: ```javascript const config = { amount: 350, currency: 'BRL', options: { enabled: true, sandbox: true, debug: true, suppressChallenge: false } }; payzu3DS.init(config); ``` | 参数 | 描述 | 类型 | | --------------------------- | ----------------------------------------------- | --------- | | `amount` | 交易总金额,单位为分 | 整数 | | `currency` | 货币代码 | 固定为 "BRL" | | `options.enabled` | 定义该交易是否提交到 3DS 认证流程 | boolean | | `options.sandbox` | 定义运行环境为 sandbox 还是生产环境 | boolean | | `options.debug` | 启用后,日志和报告将输出到浏览器控制台 | boolean | | `options.suppressChallenge` | 决定是否跳过挑战验证。如果跳过挑战验证且交易被授权,责任 (liability) 仍由商户承担 | boolean | ### 注册认证事件 [#注册认证事件] 注册事件监听器,以处理认证的每一种可能结果: ```javascript payzu3DS.on("ready", function (e) { }); ``` #### ready [#ready] 当脚本的所有加载步骤成功完成(包括访问 token 的校验)时触发此事件,表示 checkout 已就绪,可以开始认证流程。 #### 认证结果 [#认证结果] 仅当认证成功完成时才发生 liability shift:此时拒付责任转移给发卡行或卡组织。在其他所有场景中,责任仍由商户承担。 | 事件 | 场景与返回 | 责任 (liability) | 建议操作 | | ------------ | ---------------------------------------- | -------------- | -------------------------------- | | `success` | 卡片符合认证条件且认证成功完成。返回 `Cavv`、`Xid` 和 `Eci`。 | 转移给发卡行 | 将 `Cavv`、`Xid` 和 `Eci` 包含在授权请求中。 | | `failure` | 卡片符合认证条件,但认证失败。仅返回 `Eci`。 | 仍由商户承担 | 如果决定继续授权,在请求中包含 `Eci`。 | | `unenrolled` | 卡片不符合认证条件:持卡人和/或发卡行未参与 3DS 计划。仅返回 `Eci`。 | 仍由商户承担 | 提示买家向发卡行确认该卡是否已开通电商认证。 | | `disabled` | 商户选择不认证,将 `options.enabled` 设为 `false`。 | 仍由商户承担 | - | | `error` | 认证流程发生系统性错误。 | 仍由商户承担 | - | #### unsupportedBrand [#unsupportedbrand] 当所用卡片的卡组织不支持 3DS 协议时触发此事件。此时不会进行认证。 #### 返回的属性 [#返回的属性] | 属性 | 描述 | 类型 | 是否必填 | | --------------- | ------------- | ------------------- | ---- | | `Cavv` | 代表认证签名的数据 | string | 是 | | `Xid` | 认证交易的标识符 | string | 否 | | `Eci` | 代表认证结果的代码 | [ECI 表](#eci-表) | 是 | | `Version` | 所使用的 3DS 协议版本 | string | 是 | | `ReferenceId` | 认证请求的标识符 | string | 是 | | `ReturnCode` | 认证的返回码 | [3DS 返回码](#3ds-返回码) | 是 | | `ReturnMessage` | 认证的返回消息 | [3DS 返回码](#3ds-返回码) | 是 | ### 发起挑战验证 [#发起挑战验证] 实例化 `paymentObject` 对象,注意下表中明确标为必填的字段。执行 checkout 时,认证流程随即启动,其结果将通过事件返回。 ```javascript const paymentObject = { installments: '01', cardnumber: '4000000000001091', cardexpirationmonth: '01', cardexpirationyear: '2027', cardalias: 'JOAO SOUZA', paymentmethod: 'Credit' } payzu3DS.checkout(paymentObject) ``` 如果认证成功完成,将触发 `success` 事件。此时会返回 `Cavv`、`Xid` 和 `Eci` 变量:应将它们发送到您的后端,并在授权时包含在请求中。在这种情况下,liability shift 转移给发卡行。 | 属性名 | 描述 | 类型 | 长度 | 是否必填 | | -------------------------------- | ------------------------------------------- | ------------------------------------------------------------- | ----- | ---- | | `installments` | 交易的分期数 | number | 2 | 是 | | `cardnumber` | 卡号 | number | 19 | 是 | | `cardexpirationmonth` | 卡片有效期的月份 | number | 2 | 是 | | `cardexpirationyear` | 卡片有效期的年份 | number | 4 | 是 | | `cardalias` | 卡面印刷的持卡人姓名 | string | 128 | 否 | | `paymentmethod` | 要认证的卡类型。多功能卡必须指定其中一种类型,Credit 或 Debit | Credit: 信用卡。Debit: 借记卡 | 6 | 是 | | `default_card` | 标识是否为客户在店铺中的默认卡 | boolean | - | 否 | | `recurring_enddate` | 标识循环扣款的结束日期 | string (YYYY-MM-DD) | 10 | 否 | | `recurring_frequency` | 标识循环扣款的频率 | number: 1 = 每月, 2 = 每两个月, 3 = 每季度, 4 = 每四个月, 6 = 每半年, 12 = 每年 | - | 否 | | `recurring_originalpurchasedate` | 产生循环扣款的首笔交易日期 | string (YYYY-MM-DD) | 10 | 否 | | `order_recurrence` | 标识该订单是否会产生后续循环扣款 | boolean | - | 否 | | `order_productcode` | 购买类型 (PHY, CHA, ACF, QCT, PAL) | string | - | 是 | | `order_countlast24hours` | 最近 24 小时内的订单数 | number | 3 | 否 | | `order_countlast6months` | 最近 6 个月内的订单数 | number | 4 | 否 | | `order_countlast1year` | 最近一年内的订单数 | number | 3 | 否 | | `order_cardattemptslast24hours` | 最近 24 小时内使用同一张卡的交易数 | number | 3 | 否 | | `order_marketingoptin` | 是否同意接收营销优惠 | boolean | - | 否 | | `order_marketingsource` | 营销活动来源 | string | 40 | 否 | | `billto_customerid` | 买家的 CPF/CNPJ | string | 11-14 | 否 | | `billto_contactname` | 账单地址的联系人姓名 | string | 120 | 是 | | `billTo_phonenumber` | 账单地址的电话 | string | 15 | 是 | | `billTo_email` | 账单地址的电子邮箱 | string | 255 | 是 | | `billTo_street1` | 账单地址的街道和门牌号 | string | 60 | 是 | | `billTo_street2` | 账单地址的补充信息和街区 | string | 60 | 是 | | `billTo_city` | 账单地址的城市 | string | 50 | 是 | | `billTo_state` | 账单地址的州缩写 | string | 2 | 是 | | `billto_zipcode` | 账单地址的邮编 | string | 8 | 是 | | `billto_country` | 账单地址的国家 | string 例: BR | 2 | 是 | | `shipto_sameasbillto` | 账单地址与收货地址相同 | boolean | - | 否 | | `shipto_addressee` | 收货地址的联系人姓名 | string | 60 | 否 | | `shipTo_phonenumber` | 收货地址的电话 | string | 15 | 否 | | `shipTo_email` | 收货地址的电子邮箱 | string | 255 | 否 | | `shipTo_street1` | 收货地址的街道和门牌号 | string | 60 | 否 | | `shipTo_street2` | 收货地址的补充信息和街区 | string | 60 | 否 | | `shipTo_city` | 收货地址的城市 | string | 50 | 否 | | `shipTo_state` | 收货地址的州缩写 | string | 2 | 否 | | `shipto_zipcode` | 收货地址的邮编 | string | 8 | 否 | | `shipto_country` | 收货地址的国家 | string 例: BR | 2 | 否 | | `shipTo_shippingmethod` | 配送方式类型 (lowcost, sameday, oneday, twoday 等) | string | - | 否 | | `shipto_firstusagedate` | 收货地址的首次使用日期 | string (YYYY-MM-DD) | 10 | 否 | 类型列沿用来源文档。在上方官方示例中,`installments`、`cardnumber`、`cardexpirationmonth` 和 `cardexpirationyear` 均以字符串形式发送;请遵循示例,尤其是 `cardnumber`,以避免数值精度丢失。 ### 在收款中使用认证结果 [#在收款中使用认证结果] 要使用 3DS 创建收款,需要将 `authenticate` 字段设为 `true`,并在 `creditCardPayment` 中提供 `externalAuthentication` 字段: ```json { "creditCardPayment": { "authenticate": true, "externalAuthentication": { "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5", "xid": "198b924ea7db1014b64c8b426a0e6f1e", "eci": "05", "version": "2.2", "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst" } } } ``` 请求的其余字段请参阅[创建收款](/docs/cartao/endpoints/charges/post_charges)。 ## 返回码与 ECI [#返回码与-eci] ### 3DS 返回码 [#3ds-返回码] 3DS 认证流程返回的代码。 | 3DS 代码 | 描述 | 建议操作 | | -------- | ------------------- | ------------------------------------------------------- | | `100` | 交易成功完成。 | - | | `101` | 请求缺少一个或多个必填字段。 | 检查响应中的 `missingField_0` 至 `missingField_N` 字段,然后重新发送请求。 | | `102` | 请求中一个或多个字段包含无效数据。 | 检查响应中的 `invalidField_0` 至 `invalidField_N` 字段,然后重新发送请求。 | | `150` | 错误:系统整体故障。 | 请等待几分钟后重新发送请求。 | | `151` | 错误:请求已被接收,但服务器发生超时。 | 请等待几分钟后重新发送请求。 | | `152` | 错误:请求已被接收,但服务发生超时。 | 请等待几分钟后重新发送请求。 | | `234` | 您的 merchant 配置存在问题。 | 请勿重新发送该请求,请联系支持团队。 | | `475` | 该客户已注册付款人认证。 | 在继续交易前,请先完成持卡人认证。 | | `476` | 无法对该客户进行认证。 | 请复核该客户的订单。 | | `MPI901` | 意外错误。 | - | | `MPI902` | 认证返回了意外响应。 | - | | `MPI900` | 发生了一个错误。 | - | | `MPI601` | 认证挑战已被省略。 | - | | `MPI600` | 卡组织不支持该认证。 | - | ### ECI 表 [#eci-表] ECI 表按卡组织显示认证结果,以及由谁承担拒付(chargeback)风险: | Mastercard | Visa | Elo | Amex | 认证结果 | 交易是否已认证? | | ------------------ | ------------- | ------------- | ------------- | -------------------------------- | -------- | | `02` | `05` | `05` | `05` | 由发卡行认证:拒付风险转由发卡行承担。 | 是 | | `01` | `06` | `06` | `06` | 由卡组织认证:拒付风险转由发卡行承担。 | 是 | | 非 `01`、`02` 和 `04` | 非 `05` 和 `06` | 非 `05` 和 `06` | 非 `05` 和 `06` | 未认证:拒付风险仍由商户承担。 | 否 | | `04` | `7` | - | - | 未认证,交易被标记为 Data Only:拒付风险仍由商户承担。 | 否 | 当交易未通过认证时,拒付风险仍由商户承担。在决定是否继续该笔收款之前,请先核对上表中的 ECI 值。 ## 参考 [#参考] * 在 sandbox 中模拟各种 3DS 认证场景的卡片:[测试卡](/docs/cartao/test-cards) # Transaction status and reasons (/docs/cartao/transaction-status.en) Build your logic on the numeric codes and stable values on this page. Descriptions and human-readable messages may change. ## Transaction status [#transaction-status] The `creditCardPayment.status` field indicates the current state of the payment. List of possible statuses returned by the API: | Code | Payment status | Description | | ---- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | `NotFinished` | Failed to process the payment. Possible causes: incorrect data, request error, timeout, processing instability. | | 1 | `Authorized` | Payment method eligible for capture. The issuing bank approved the transaction, but this does not mean the transaction is complete. | | 2 | `PaymentConfirmed` | Payment confirmed and finalized. | | 3 | `Denied` | Payment denied by an authorizer. Possible causes: insufficient limit, card payment overdue, brand unavailable, fraud block, among others. | | 10 | `Voided` | Payment canceled. | | 11 | `Refunded` | Payment canceled/refunded. It means a cancellation of the transaction was requested. | | 12 | `Pending` | Waiting for a response from the financial institution. It means the transaction was sent for pre-authorization and is waiting for a response from the bank to validate it. | | 13 | `Aborted` | Payment canceled due to a processing failure. The transaction was canceled because of a processing failure, or the anti-fraud system denied the transaction before authorization. | Status `1` (`Authorized`) only indicates that the issuer approved the transaction. Payment completion is confirmed by status `2` (`PaymentConfirmed`). ## ReasonCode and ReasonMessage [#reasoncode-and-reasonmessage] The `reasonCode` and `reasonMessage` fields detail the reason for the transaction result, including when the result comes from the antifraud analysis, as in `AbortedByFraud` and `CouldNotAntifraud`. | `reasonCode` | `reasonMessage` | | ------------ | ------------------------------ | | 0 | `Successful` | | 1 | `AffiliationNotFound` | | 2 | `InsufficientFunds` | | 3 | `CouldNotGetCreditCard` | | 4 | `ConnectionWithAcquirerFailed` | | 5 | `InvalidTransactionType` | | 6 | `InvalidPaymentPlan` | | 7 | `Denied` | | 8 | `Scheduled` | | 9 | `Waiting` | | 10 | `Authenticated` | | 11 | `NotAuthenticated` | | 12 | `ProblemsWithCreditCard` | | 13 | `CardCanceled` | | 14 | `BlockedCreditCard` | | 15 | `CardExpired` | | 16 | `AbortedByFraud` | | 17 | `CouldNotAntifraud` | | 18 | `TryAgain` | | 19 | `InvalidAmount` | | 20 | `ProblemsWithIssuer` | | 21 | `InvalidCardNumber` | | 22 | `TimeOut` | | 23 | `CartaoProtegidoIsNotEnabled` | | 24 | `PaymentMethodIsNotEnabled` | | 98 | `InvalidRequest` | | 99 | `InternalError` | ## Chargeback status [#chargeback-status] The `chargebacks[].status` field indicates the state of each chargeback associated with the charge: | Value | Description | | ---------- | ------------------------------------ | | `RECEIVED` | Chargeback received. | | `ACCEPTED` | Chargeback accepted by the merchant. | | `DEFENDED` | Chargeback disputed by the merchant. | # Status e motivos da transação (/docs/cartao/transaction-status) Programe sua lógica pelos códigos numéricos e valores estáveis desta página. As descrições e mensagens legíveis podem mudar. ## Status da transação [#status-da-transação] O campo `creditCardPayment.status` indica o estado atual do pagamento. Lista de possíveis status retornados pela API: | Código | Status do pagamento | Descrição | | ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0 | `NotFinished` | Falha ao processar o pagamento. Possíveis causas: dados incorretos, erro na requisição, timeout, instabilidade no processamento. | | 1 | `Authorized` | Meio de pagamento apto a ser capturado. O banco emissor aprovou a transação, porém isso não significa que a transação foi concluída. | | 2 | `PaymentConfirmed` | Pagamento confirmado e finalizado. | | 3 | `Denied` | Pagamento negado por autorizador. Possíveis causas: limite insuficiente, falta de pagamento do cartão, bandeira indisponível, bloqueio por fraude, entre outros. | | 10 | `Voided` | Pagamento cancelado. | | 11 | `Refunded` | Pagamento cancelado/estornado. Significa que foi solicitado o cancelamento da transação. | | 12 | `Pending` | Esperando retorno da instituição financeira. Significa que a transação foi enviada em processo de pré-autorização e está esperando uma resposta do banco para validá-la. | | 13 | `Aborted` | Pagamento cancelado por falha no processamento. A transação foi cancelada por falha no processamento, ou o antifraude negou a transação antes da autorização. | O status `1` (`Authorized`) indica apenas que o emissor aprovou a transação. A conclusão do pagamento é confirmada pelo status `2` (`PaymentConfirmed`). ## ReasonCode e ReasonMessage [#reasoncode-e-reasonmessage] Os campos `reasonCode` e `reasonMessage` detalham o motivo do resultado da transação, inclusive quando o resultado vem da análise antifraude, como em `AbortedByFraud` e `CouldNotAntifraud`. | `reasonCode` | `reasonMessage` | | ------------ | ------------------------------ | | 0 | `Successful` | | 1 | `AffiliationNotFound` | | 2 | `InsufficientFunds` | | 3 | `CouldNotGetCreditCard` | | 4 | `ConnectionWithAcquirerFailed` | | 5 | `InvalidTransactionType` | | 6 | `InvalidPaymentPlan` | | 7 | `Denied` | | 8 | `Scheduled` | | 9 | `Waiting` | | 10 | `Authenticated` | | 11 | `NotAuthenticated` | | 12 | `ProblemsWithCreditCard` | | 13 | `CardCanceled` | | 14 | `BlockedCreditCard` | | 15 | `CardExpired` | | 16 | `AbortedByFraud` | | 17 | `CouldNotAntifraud` | | 18 | `TryAgain` | | 19 | `InvalidAmount` | | 20 | `ProblemsWithIssuer` | | 21 | `InvalidCardNumber` | | 22 | `TimeOut` | | 23 | `CartaoProtegidoIsNotEnabled` | | 24 | `PaymentMethodIsNotEnabled` | | 98 | `InvalidRequest` | | 99 | `InternalError` | ## Status do chargeback [#status-do-chargeback] O campo `chargebacks[].status` indica o estado de cada chargeback associado à cobrança: | Valor | Descrição | | ---------- | -------------------------------- | | `RECEIVED` | Chargeback recebido. | | `ACCEPTED` | Chargeback aceito pela loja. | | `DEFENDED` | Chargeback contestado pela loja. | # 交易状态与原因 (/docs/cartao/transaction-status.zh) 请基于本页的数字代码和稳定值来编写业务逻辑。可读的描述和消息文案可能会发生变化。 ## 交易状态 [#交易状态] `creditCardPayment.status` 字段表示支付的当前状态。API 可能返回的状态列表: | 代码 | 支付状态 | 描述 | | -- | ------------------ | ------------------------------------------- | | 0 | `NotFinished` | 支付处理失败。可能原因:数据不正确、请求错误、超时、处理过程不稳定。 | | 1 | `Authorized` | 支付方式已具备扣款(capture)条件。发卡行已批准该交易,但这并不代表交易已完成。 | | 2 | `PaymentConfirmed` | 支付已确认并完成。 | | 3 | `Denied` | 支付被授权方拒绝。可能原因:额度不足、卡片欠款、卡组织不可用、疑似欺诈被拦截等。 | | 10 | `Voided` | 支付已取消。 | | 11 | `Refunded` | 支付已取消/已退款。表示已发起该笔交易的取消请求。 | | 12 | `Pending` | 等待金融机构返回结果。表示交易已进入预授权流程,正在等待银行的响应以完成校验。 | | 13 | `Aborted` | 支付因处理失败而被取消。交易因处理失败被取消,或反欺诈系统在授权前拒绝了该交易。 | 状态 `1`(`Authorized`)仅表示发卡行批准了该交易。支付的最终完成以状态 `2`(`PaymentConfirmed`)为准。 ## ReasonCode 和 ReasonMessage [#reasoncode-和-reasonmessage] `reasonCode` 和 `reasonMessage` 字段说明交易结果的原因，包括结果来自反欺诈分析的情况，例如 `AbortedByFraud` 和 `CouldNotAntifraud`。 | `reasonCode` | `reasonMessage` | | ------------ | ------------------------------ | | 0 | `Successful` | | 1 | `AffiliationNotFound` | | 2 | `InsufficientFunds` | | 3 | `CouldNotGetCreditCard` | | 4 | `ConnectionWithAcquirerFailed` | | 5 | `InvalidTransactionType` | | 6 | `InvalidPaymentPlan` | | 7 | `Denied` | | 8 | `Scheduled` | | 9 | `Waiting` | | 10 | `Authenticated` | | 11 | `NotAuthenticated` | | 12 | `ProblemsWithCreditCard` | | 13 | `CardCanceled` | | 14 | `BlockedCreditCard` | | 15 | `CardExpired` | | 16 | `AbortedByFraud` | | 17 | `CouldNotAntifraud` | | 18 | `TryAgain` | | 19 | `InvalidAmount` | | 20 | `ProblemsWithIssuer` | | 21 | `InvalidCardNumber` | | 22 | `TimeOut` | | 23 | `CartaoProtegidoIsNotEnabled` | | 24 | `PaymentMethodIsNotEnabled` | | 98 | `InvalidRequest` | | 99 | `InternalError` | ## 拒付状态 [#拒付状态] `chargebacks[].status` 字段表示与该笔收款关联的每笔拒付的状态: | 值 | 描述 | | ---------- | ----------- | | `RECEIVED` | 已收到拒付。 | | `ACCEPTED` | 商户已接受拒付。 | | `DEFENDED` | 商户已对拒付提出抗辩。 | # Webhooks (/docs/cartao/webhooks.en) Instead of your system polling "has it been paid yet?", PayZu **calls you** when something happens: a charge status change, a fraud analysis update, a chargeback or a new recurrence cycle. ## How to configure [#how-to-configure] Provide the `postbackUrl` when creating the charge ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)). Whenever an event occurs, PayZu sends a `POST` request in JSON to that URL. ## Events [#events] | Event types | Description | | ------------------ | ------------------------------------------------------- | | `charge.update` | Payment status change | | `antifraud.update` | Fraud analysis status change | | `chargeback` | Chargeback notification | | `recurrence.cycle` | New [recurrence](/docs/cartao/recurrence) cycle charged | ## Payload structure [#payload-structure] | Parameters | Description | Type | | ---------- | -------------------------------- | ------------------------------------------------------------------------------------------ | | `event` | Event that triggered the webhook | See the [events](#events) table | | `data` | Updated charge data | Same value returned by [Get Charge](/docs/cartao/endpoints/charges/get_charges__chargeId_) | ```json { "event": "charge.update", "data": {} } ``` The `data` object has exactly the same format as the [Get Charge](/docs/cartao/endpoints/charges/get_charges__chargeId_) response. ## Request headers [#request-headers] Every `POST` arrives with the following headers: | Header | Description | | --------------------- | --------------------------------------------------------------------- | | `Content-Type` | Always `application/json` | | `X-Webhook-Signature` | HMAC SHA-256 signature of the payload, in hexadecimal (64 characters) | | `X-Webhook-Timestamp` | Time of sending, in milliseconds since the Unix epoch | | `X-Webhook-Nonce` | Unique identifier of the request (32 hexadecimal characters) | ## Retries [#retries] The first delivery happens as soon as the event occurs. The delivery is only considered successful if your URL responds with an HTTP `2xx` status within **5 seconds**: any other status, or a slower response, counts as a failure. After a failure, the webhook makes up to **5 retries**. After each failure, the time until the next attempt increases: the retries are made, respectively, after 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours. After that, the attempts stop. Respond to the webhook quickly (a simple `200` is enough) and process the payload asynchronously, so you do not exceed the 5-second limit. Since a timeout can trigger a redelivery of an event you already processed, consumption must be idempotent: use the charge `id` combined with the status transition as your deduplication key. Do not use `X-Webhook-Nonce` for this, it identifies the HTTP request and changes on every redelivery. ## HMAC verification [#hmac-verification] Every webhook is signed with your **webhook secret**, provided by PayZu along with your [API credentials](/docs/cartao/authentication). Your API must validate the signature before processing the payload: Extract the `x-webhook-timestamp`, `x-webhook-nonce` and `x-webhook-signature` headers. Concatenate the timestamp, nonce and payload values, separated by `.`, forming the verification base string: `timestamp.nonce.payload`. Generate an HMAC signature with the SHA-256 algorithm from that string, using your webhook secret. Compare the generated signature with the value of the `x-webhook-signature` header. If they do not match, reject the webhook. Example in Node.js, using `crypto.timingSafeEqual` to compare the signatures in constant time: ```js const crypto = require("node:crypto"); function verifyWebhookSignature(request, webhookSecret) { const timestamp = request.headers["x-webhook-timestamp"]; const nonce = request.headers["x-webhook-nonce"]; const signature = request.headers["x-webhook-signature"]; if (typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature)) { return false; } const baseString = `${timestamp}.${nonce}.${request.rawBody}`; const expectedSignature = crypto .createHmac("sha256", webhookSecret) .update(baseString) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(expectedSignature, "hex"), Buffer.from(signature, "hex"), ); } ``` Compute the HMAC over the raw request body, exactly as received, before any JSON parsing. ## Nonce verification (optional) [#nonce-verification-optional] The value of the `x-webhook-nonce` header acts as a unique, temporary identifier for each request. After extracting it, check whether that nonce has been recorded before: * If the value has already been used, reject the request to mitigate replay attacks. * If the nonce is new, store it as used, ensuring it cannot be reused in future calls. ## Timestamp verification (optional) [#timestamp-verification-optional] The value of the `x-webhook-timestamp` header is the time of sending in **milliseconds** since the Unix epoch. Compare it with the current time: if the difference is greater than **5 minutes**, reject the request. This validation discards expired webhooks, preventing the processing of old or potentially malicious messages. # Webhooks (/docs/cartao/webhooks) Em vez do seu sistema ficar perguntando "já pagou?", a PayZu **chama você** quando algo acontece: mudança de status da cobrança, atualização do antifraude, chargeback ou um novo ciclo de recorrência. ## Como configurar [#como-configurar] Informe a `postbackUrl` na criação da cobrança ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)). Sempre que houver um evento, a PayZu envia uma requisição `POST` em JSON para essa URL. ## Eventos [#eventos] | Tipos de evento | Descrição | | ------------------ | ------------------------------------------------------------ | | `charge.update` | Mudança no status de pagamento | | `antifraud.update` | Mudança de status do Antifraude | | `chargeback` | Notificação de chargeback | | `recurrence.cycle` | Novo ciclo de [recorrência](/docs/cartao/recurrence) cobrado | ## Estrutura do payload [#estrutura-do-payload] | Parâmetros | Descrição | Tipo | | ---------- | ----------------------------- | ----------------------------------------------------------------------------------------------------- | | `event` | Evento que chamou o webhook | Ver a tabela de [eventos](#eventos) | | `data` | Dados atualizados da cobrança | Mesmo valor retornado por [Consultar Cobrança](/docs/cartao/endpoints/charges/get_charges__chargeId_) | ```json { "event": "charge.update", "data": {} } ``` O objeto `data` tem exatamente o mesmo formato da resposta de [Consultar Cobrança](/docs/cartao/endpoints/charges/get_charges__chargeId_). ## Cabeçalhos da requisição [#cabeçalhos-da-requisição] Cada `POST` chega com os seguintes cabeçalhos: | Cabeçalho | Descrição | | --------------------- | ------------------------------------------------------------------ | | `Content-Type` | Sempre `application/json` | | `X-Webhook-Signature` | Assinatura HMAC SHA-256 do payload, em hexadecimal (64 caracteres) | | `X-Webhook-Timestamp` | Instante do envio, em milissegundos desde a época Unix | | `X-Webhook-Nonce` | Identificador único da requisição (32 caracteres hexadecimais) | Nomes de cabeçalho HTTP não diferenciam maiúsculas de minúsculas: dependendo do framework, eles chegam normalizados como `x-webhook-signature`, `x-webhook-timestamp` e `x-webhook-nonce`. ## Retentativas [#retentativas] O primeiro envio acontece assim que o evento ocorre. A entrega só é considerada bem-sucedida se a sua URL responder com um status HTTP `2xx` em até **5 segundos**: qualquer outro status, ou uma resposta mais lenta que isso, conta como falha. Depois de uma falha, o webhook faz até **5 retentativas**. A cada falha, o tempo até a próxima tentativa aumenta: as retentativas são feitas, respectivamente, depois de 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas. Depois disso, as tentativas param. Responda o webhook rapidamente (um `200` simples basta) e processe o payload de forma assíncrona, para não estourar o limite de 5 segundos. Como um timeout pode gerar reenvio de um evento que você já processou, o consumo precisa ser idempotente: use o `id` da cobrança combinado com a transição de status como chave de deduplicação. Não use o `X-Webhook-Nonce` para isso, ele identifica a requisição HTTP e muda a cada reenvio. ## Verificação HMAC [#verificação-hmac] Cada webhook é assinado com o seu **webhook secret**, fornecido pela PayZu junto com as suas [credenciais de API](/docs/cartao/authentication). Sua API deve validar a assinatura antes de processar o payload: Extraia os cabeçalhos `x-webhook-timestamp`, `x-webhook-nonce` e `x-webhook-signature`. Concatene os valores do timestamp, do nonce e do payload, separados por `.`, formando a string base de verificação: `timestamp.nonce.payload`. Gere uma assinatura HMAC com o algoritmo SHA-256 a partir dessa string, usando o seu webhook secret. Compare a assinatura gerada com o valor do cabeçalho `x-webhook-signature`. Se não coincidirem, rejeite o webhook. Exemplo em Node.js, usando `crypto.timingSafeEqual` para comparar as assinaturas em tempo constante: ```js const crypto = require("node:crypto"); function verifyWebhookSignature(request, webhookSecret) { const timestamp = request.headers["x-webhook-timestamp"]; const nonce = request.headers["x-webhook-nonce"]; const signature = request.headers["x-webhook-signature"]; if (typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature)) { return false; } const baseString = `${timestamp}.${nonce}.${request.rawBody}`; const expectedSignature = crypto .createHmac("sha256", webhookSecret) .update(baseString) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(expectedSignature, "hex"), Buffer.from(signature, "hex"), ); } ``` Calcule o HMAC sobre o corpo bruto da requisição (raw body), exatamente como recebido, antes de qualquer parse de JSON. ## Verificação do nonce (opcional) [#verificação-do-nonce-opcional] O valor do cabeçalho `x-webhook-nonce` atua como identificador único e temporário de cada requisição. Após extraí-lo, verifique se esse nonce já foi registrado antes: * Se o valor já tiver sido utilizado, rejeite a requisição para mitigar ataques de repetição (replay attacks). * Se o nonce for novo, armazene-o como utilizado, garantindo que não possa ser reaproveitado em chamadas futuras. ## Verificação do timestamp (opcional) [#verificação-do-timestamp-opcional] O valor do cabeçalho `x-webhook-timestamp` é o instante do envio em **milissegundos** desde a época Unix. Compare-o com o horário atual: se a diferença for superior a **5 minutos**, rejeite a requisição. Essa validação descarta webhooks expirados, evitando o processamento de mensagens antigas ou potencialmente maliciosas. # Webhooks (/docs/cartao/webhooks.zh) 您的系统无需反复轮询"付款了吗?",有事件发生时 PayZu 会**主动调用您**:收款状态变化、反欺诈状态更新、拒付(chargeback)或新的循环扣款周期。 ## 如何配置 [#如何配置] 在创建收款时([`POST /charges`](/docs/cartao/endpoints/charges/post_charges))提供 `postbackUrl`。每当有事件发生,PayZu 都会向该 URL 发送一个 JSON 格式的 `POST` 请求。 ## 事件 [#事件] | 事件类型 | 说明 | | ------------------ | -------------------------------------- | | `charge.update` | 支付状态变化 | | `antifraud.update` | 反欺诈状态变化 | | `chargeback` | 拒付通知 | | `recurrence.cycle` | 新的[循环扣款](/docs/cartao/recurrence)周期已扣款 | ## Payload 结构 [#payload-结构] | 参数 | 说明 | 类型 | | ------- | -------------- | -------------------------------------------------------------------- | | `event` | 触发 webhook 的事件 | 参见[事件](#事件)表 | | `data` | 收款的最新数据 | 与[查询收款](/docs/cartao/endpoints/charges/get_charges__chargeId_)返回的值相同 | ```json { "event": "charge.update", "data": {} } ``` `data` 对象的格式与[查询收款](/docs/cartao/endpoints/charges/get_charges__chargeId_)的响应完全一致。 ## 请求 Header [#请求-header] 每个 `POST` 请求都带有以下 header: | Header | 说明 | | --------------------- | ---------------------------------------- | | `Content-Type` | 始终为 `application/json` | | `X-Webhook-Signature` | Payload 的 HMAC SHA-256 签名,十六进制格式(64 个字符) | | `X-Webhook-Timestamp` | 发送时刻,自 Unix 纪元起的毫秒数 | | `X-Webhook-Nonce` | 请求的唯一标识符(32 个十六进制字符) | ## 重试 [#重试] 事件发生后会立即进行首次投递。只有当您的 URL 在 **5 秒**内返回 HTTP `2xx` 状态码,投递才视为成功:任何其他状态码或超时的响应均视为失败。 投递失败后,webhook 最多进行 **5 次重试**。每次失败后,距下一次尝试的间隔逐步增大:各次重试分别在 1 分钟、10 分钟、1 小时、6 小时和 24 小时后进行。此后不再重试。 请尽快响应 webhook(返回一个简单的 `200` 即可),并异步处理 payload,以免超出 5 秒的限制。由于超时可能导致已处理过的事件被重新投递，消费必须是幂等的：请使用收款的 `id` 加上状态变化作为去重键。不要用 `X-Webhook-Nonce` 去重，它标识的是 HTTP 请求，每次重新投递都会变化。 ## HMAC 验证 [#hmac-验证] 每个 webhook 都使用您的 **webhook secret** 签名,该密钥由 PayZu 随您的 [API 凭据](/docs/cartao/authentication)一同提供。您的 API 应在处理 payload 之前先验证签名: 提取 `x-webhook-timestamp`、`x-webhook-nonce` 和 `x-webhook-signature` 三个 header。 将 timestamp、nonce 和 payload 的值用 `.` 连接,得到验证基础字符串:`timestamp.nonce.payload`。 使用您的 webhook secret,对该字符串以 SHA-256 算法生成 HMAC 签名。 将生成的签名与 `x-webhook-signature` header 的值比较。不一致则拒绝该 webhook。 Node.js 示例,使用 `crypto.timingSafeEqual` 以恒定时间比较签名: ```js const crypto = require("node:crypto"); function verifyWebhookSignature(request, webhookSecret) { const timestamp = request.headers["x-webhook-timestamp"]; const nonce = request.headers["x-webhook-nonce"]; const signature = request.headers["x-webhook-signature"]; if (typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature)) { return false; } const baseString = `${timestamp}.${nonce}.${request.rawBody}`; const expectedSignature = crypto .createHmac("sha256", webhookSecret) .update(baseString) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(expectedSignature, "hex"), Buffer.from(signature, "hex"), ); } ``` HMAC 必须基于请求的原始报文体(raw body)计算,即收到的原样内容,在任何 JSON 解析之前。 ## Nonce 验证(可选) [#nonce-验证可选] `x-webhook-nonce` header 的值是每个请求唯一且临时的标识符。提取后,检查该 nonce 是否已被记录过: * 若该值已被使用过,则拒绝请求,以防范重放攻击(replay attacks)。 * 若 nonce 是新的,则将其记录为已使用,确保后续调用无法重复使用。 ## Timestamp 验证(可选) [#timestamp-验证可选] `x-webhook-timestamp` header 的值是发送时刻自 Unix 纪元起的**毫秒**数。将其与当前时间比较:若差值超过 **5 分钟**,则拒绝请求。此项校验可丢弃已过期的 webhook,避免处理陈旧或潜在恶意的消息。 # API Endpoints (/docs/cartao/endpoints/index.en) ## Typical integration flow [#typical-integration-flow] You get a token, create the charge, receive the webhook with the result, query the state whenever you need and reverse it if applicable. ## Token [#token] API authentication: exchange `client_id` and `client_secret` for a JWT token. ## Charges [#charges] Creation, query and reversal of credit card charges. ## Recurrences [#recurrences] Management of subscriptions created with the `recurrence` node in `POST /charges`. ## Currencies [#currencies] Reference rates and conversion for international charges. ## Conventions [#conventions] | Item | Value | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL (production) | `https://api.payzu.io/v1` | | Base URL (sandbox) | `https://api.sandbox.payzu.io/v1` | | Authentication | mTLS (client certificate) + `Authorization: Bearer YOUR_TOKEN`, obtained from [`POST /token`](/docs/cartao/endpoints/token/post_token). See [Authentication](/docs/cartao/authentication) | | Content-Type | `application/json` | | Amounts | In cents (`10000` = R$ 100.00) | # Endpoints da API (/docs/cartao/endpoints) ## Fluxo típico de integração [#fluxo-típico-de-integração] Você obtém um token, cria a cobrança, recebe o webhook com o resultado, consulta o estado quando precisar e estorna se for o caso. ## Token [#token] Autenticação da API: troque `client_id` e `client_secret` por um token JWT. ## Cobranças [#cobranças] Criação, consulta e estorno de cobranças com cartão de crédito. ## Recorrências [#recorrências] Gestão de assinaturas criadas com o nó `recurrence` no `POST /charges`. ## Câmbio [#câmbio] Cotações de referência e conversão para cobrança internacional. ## Convenções [#convenções] | Item | Valor | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL (produção) | `https://api.payzu.io/v1` | | Base URL (sandbox) | `https://api.sandbox.payzu.io/v1` | | Autenticação | mTLS (certificado de cliente) + `Authorization: Bearer SEU_TOKEN`, obtido no [`POST /token`](/docs/cartao/endpoints/token/post_token). Veja [Autenticação](/docs/cartao/authentication) | | Content-Type | `application/json` | | Valores | Em centavos (`10000` = R$ 100,00) | # API 端点 (/docs/cartao/endpoints/index.zh) ## 典型集成流程 [#典型集成流程] 流程是:获取 token,创建收款,通过 webhook 接收处理结果,需要时查询状态,必要时发起退款。 ## Token [#token] API 身份认证:用 `client_id` 和 `client_secret` 换取 JWT token。 ## 收款 [#收款] 创建、查询和退款信用卡收款。 ## 循环扣款 [#循环扣款] 管理通过 `POST /charges` 中的 `recurrence` 节点创建的订阅。 ## 汇率 [#汇率] 用于国际收款的参考汇率与换算。 ## 约定 [#约定] | 项目 | 值 | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL(生产环境) | `https://api.payzu.io/v1` | | Base URL(sandbox) | `https://api.sandbox.payzu.io/v1` | | 身份认证 | mTLS(客户端证书)+ `Authorization: Bearer YOUR_TOKEN`,通过 [`POST /token`](/docs/cartao/endpoints/token/post_token) 获取。参见[身份认证](/docs/cartao/authentication) | | Content-Type | `application/json` | | 金额 | 以分为单位(`10000` = R$ 100,00) | # Models (/docs/cartao/endpoints/models.en) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} The models below describe the objects accepted and returned by the endpoints. Field names are case sensitive and monetary values are always in cents. ## Address [#address] Billing address | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------- | | `street` | string | Yes | Billing address street | | `number` | string | Yes | Billing address number | | `complement` | string | No | Billing address complement | | `zipCode` | string | Yes | Billing address postal code | | `city` | string | Yes | Billing address city | | `state` | string | Yes | Billing address state | | `country` | string | Yes | Billing address country | | `district` | string | Yes | Billing address district | ## CustomerRequest [#customerrequest] Buyer data | Field | Type | Required | Description | | -------------- | ------------------- | -------- | -------------------------------------- | | `name` | string | Yes | Buyer's full name | | `identity` | string | No | Buyer's identification document number | | `identityType` | string | No | Buyer's identification document type | | `email` | string | No | Buyer's email | | `birthdate` | string | No | Buyer's birthdate | | `phone` | string | No | Buyer's phone number | | `address` | [Address](#address) | No | | ## CustomerResponse [#customerresponse] Buyer data | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------- | | `id` | number | No | Internal buyer identifier | | `name` | string | No | Buyer's full name | | `identity` | string | No | Buyer's identification document number | | `identityType` | string | No | Buyer's identification document type | | `email` | string | No | Buyer's email | | `birthdate` | string | No | Buyer's birthdate | | `phone` | string | No | Buyer's phone number | | `address` | object | No | Billing address | ## CartItem [#cartitem] | Field | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------- | | `name` | string | Yes | Product name | | `quantity` | number | Yes | Product quantity | | `sku` | string | Yes | Product SKU (Stock Keeping Unit) | | `unitPrice` | number | Yes | Product unit price in cents | ## CardRequest [#cardrequest] Card details | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------- | | `number` | string | Yes | Credit card number | | `holder` | string | Yes | Cardholder name as printed on the credit card | | `expiration` | string | Yes | Credit card expiration date | | `cvv` | string | Yes | Security code on the back of the credit card | ## CardResponse [#cardresponse] Details of the card used in the charge | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | No | Internal card identifier | | `number` | string | No | Credit card number | | `holder` | string | No | Cardholder name as printed on the credit card | | `expiration` | string | No | Credit card expiration date | | `brand` | string | No | Card brand. See [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). Values: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] 3DS authentication data performed outside PayZu (external authentication) | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `cavv` | string | Yes | Signature returned on successful authentication scenarios | | `xid` | string | No | XID returned in the authentication process | | `eci` | string | Yes | Electronic Commerce Indicator returned in the authentication process. See [ECI table](https://docs.payzu.com.br/docs/cartao/three-d-secure) | | `version` | string | Yes | 3DS version applied in the authentication process | | `referenceId` | string | Yes | RequestID returned in the authentication process | ## FraudAnalysis [#fraudanalysis] Data for the antifraud engine. Required on international charges. See [Using Antifraud](https://docs.payzu.com.br/docs/cartao/antifraud) | Field | Type | Required | Description | | --------------- | --------- | -------- | ---------------------------------------------------------------------------------------- | | `fingerPrintId` | string | Yes | Identifier used to correlate information collected from the buyer's device | | `browser` | object | Yes | Information about the buyer's browser | | `definedFields` | object\[] | Yes | Merchant Defined Data (MDD). See [MDD table](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | Field | Type | Required | Description | | ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | No | Chargeback identifier | | `number` | string | No | Chargeback number at the acquirer | | `amount` | number | No | Chargeback amount in cents | | `status` | string | No | Chargeback status. See [Chargeback status list](https://docs.payzu.com.br/docs/cartao/transaction-status). Values: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | No | Reason code provided by the card brand | | `reasonDescription` | string | No | Reason description provided by the card brand | | `issuedAt` | string | No | Chargeback issue date | | `createdAt` | string | No | Record creation date | | `updatedAt` | string | No | Date the record was last updated | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Credit card payment details | Field | Type | Required | Description | | ------------------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installments` | number | No | Number of installments | | `authenticate` | boolean | No | Indicates whether the buyer was redirected to the issuer for 3DS authentication | | `currency` | string | No | Charge currency. See [Currencies](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | No | Transaction identifier at the acquirer | | `authorizationCode` | string | No | Authorization code returned by the acquirer | | `reasonCode` | number | No | Reason code of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | No | Reason message of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | No | Transaction status. See [Transaction status list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | No | Return code from the acquirer. See [Error Codes](https://docs.payzu.com.br/docs/cartao/error-codes) and [ABECS return codes](https://docs.payzu.com.br/docs/cartao/abecs-codes) | | `returnMessage` | string | No | Return message from the acquirer | | `externalAuthentication` | object | No | External 3DS authentication data, when sent at creation | | `reversedAmount` | number | No | Reversed amount in cents, when a reversal exists | | `reversedDate` | string | No | Reversal date, when present | | `chargeId` | string | No | Charge identifier | | `card` | [CardResponse](#cardresponse) | No | | | `chargebacks` | [Chargeback](#chargeback)\[] | No | Chargebacks linked to the charge | ## RecurrenceRequest [#recurrencerequest] Recurring payment configuration. The first charge is created immediately; the following cycles are generated automatically. Requires `installments` equal to 1. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence) | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- | | `interval` | string | Yes | Interval between charges: `Monthly` or `Annual`. Values: `Monthly`, `Annual` | | `endDate` | string | No | Recurrence end date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely | ## Recurrence [#recurrence] State of a recurrence | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `recurrentPaymentId` | string | No | Recurrence identifier. Use it on the recurrence query and management endpoints | | `interval` | string | No | Configured interval. Values: `MONTHLY`, `ANNUAL` | | `status` | string | No | Recurrence status. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence). Values: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | No | Amount of each cycle, in cents | | `nextRecurrency` | string | No | Date of the next automatic charge | | `endDate` | string | No | End date, if provided at creation | ## Charge [#charge] | Field | Type | Required | Description | | ------------------- | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | No | Charge identifier | | `externalId` | string | No | Unique identifier generated externally | | `postbackUrl` | string | No | Url for notifications about the charge status | | `amount` | number | No | Charge amount in cents | | `paymentType` | string | No | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | No | Charge creation date | | `updatedAt` | string | No | Date the charge was last updated | | `customer` | [CustomerResponse](#customerresponse) | No | | | `cart` | [CartItem](#cartitem)\[] | No | Buyer's cart | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | No | | | `recurrence` | [Recurrence](#recurrence) | No | Present when the charge belongs to a recurrence | | `recurrenceCycle` | integer | No | Cycle number of the recurrence this charge belongs to: 0 is the initial charge, 1..n are the automatically generated cycles. Present only on recurrence charges | ## ChargeRequest [#chargerequest] | Field | Type | Required | Description | | ------------------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `amount` | number | Yes | Charge amount in cents | | `customer` | [CustomerRequest](#customerrequest) | Yes | | | `postbackUrl` | string | No | Url for notifications about the charge status. See [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | Yes | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes). Values: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | Yes | Buyer's cart | | `creditCardPayment` | object | Yes | Settings for the payment type: credit card | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | No | | | `externalId` | string | Yes | Unique identifier generated externally | # Modelos (/docs/cartao/endpoints/models) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} Os modelos abaixo descrevem os objetos aceitos e retornados pelos endpoints. Os nomes de campo diferenciam maiúsculas de minúsculas e os valores monetários são sempre em centavos. ## Address [#address] Endereço de cobrança | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------- | | `street` | string | Sim | Logradouro do endereço de cobrança | | `number` | string | Sim | Número do endereço de cobrança | | `complement` | string | Não | Complemento do endereço de cobrança | | `zipCode` | string | Sim | Código postal do endereço de cobrança | | `city` | string | Sim | Cidade do endereço de cobrança | | `state` | string | Sim | Estado do endereço de cobrança | | `country` | string | Sim | País do endereço de cobrança | | `district` | string | Sim | Bairro do endereço de cobrança | ## CustomerRequest [#customerrequest] Dados do comprador | Campo | Tipo | Obrigatório | Descrição | | -------------- | ------------------- | ----------- | ------------------------------------------------- | | `name` | string | Sim | Nome completo do comprador | | `identity` | string | Não | Número do documento de identificação do comprador | | `identityType` | string | Não | Tipo de documento de identificação do comprador | | `email` | string | Não | E-mail do comprador | | `birthdate` | string | Não | Data de nascimento do comprador | | `phone` | string | Não | Número do telefone do comprador | | `address` | [Address](#address) | Não | | ## CustomerResponse [#customerresponse] Dados do comprador | Campo | Tipo | Obrigatório | Descrição | | -------------- | ------ | ----------- | ------------------------------------------------- | | `id` | number | Não | Identificador interno do comprador | | `name` | string | Não | Nome completo do comprador | | `identity` | string | Não | Número do documento de identificação do comprador | | `identityType` | string | Não | Tipo de documento de identificação do comprador | | `email` | string | Não | E-mail do comprador | | `birthdate` | string | Não | Data de nascimento do comprador | | `phone` | string | Não | Número do telefone do comprador | | `address` | object | Não | Endereço de cobrança | ## CartItem [#cartitem] | Campo | Tipo | Obrigatório | Descrição | | ----------- | ------ | ----------- | -------------------------------------------------------------------- | | `name` | string | Sim | Nome do produto | | `quantity` | number | Sim | Quantidade do produto | | `sku` | string | Sim | SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto | | `unitPrice` | number | Sim | Preço unitário do produto em centavos | ## CardRequest [#cardrequest] Detalhes do cartão | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------------------- | | `number` | string | Sim | Número do cartão de crédito | | `holder` | string | Sim | Nome do portador impresso no cartão de crédito | | `expiration` | string | Sim | Data de validade do cartão de crédito | | `cvv` | string | Sim | Código de segurança no verso do cartão de crédito | ## CardResponse [#cardresponse] Detalhes do cartão utilizado na cobrança | Campo | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | number | Não | Identificador interno do cartão | | `number` | string | Não | Número do cartão de crédito | | `holder` | string | Não | Nome do portador impresso no cartão de crédito | | `expiration` | string | Não | Data de validade do cartão de crédito | | `brand` | string | Não | Bandeira do cartão. Veja [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). Valores: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] Dados de autenticação 3DS realizada fora da PayZu (autenticação externa) | Campo | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `cavv` | string | Sim | Assinatura retornada nos cenários de sucesso na autenticação | | `xid` | string | Não | XID retornado no processo de autenticação | | `eci` | string | Sim | Electronic Commerce Indicator retornado no processo de autenticação. Veja [Tabela ECI](https://docs.payzu.com.br/docs/cartao/three-d-secure) | | `version` | string | Sim | Versão do 3DS aplicado no processo de autenticação | | `referenceId` | string | Sim | RequestID retornado no processo de autenticação | ## FraudAnalysis [#fraudanalysis] Dados para o motor antifraude. Obrigatório em cobranças internacionais. Veja [Utilizando Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud) | Campo | Tipo | Obrigatório | Descrição | | --------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------- | | `fingerPrintId` | string | Sim | Identificador utilizado para cruzar informações obtidas do dispositivo do comprador | | `browser` | object | Sim | Informações sobre o navegador do comprador | | `definedFields` | object\[] | Sim | Merchant Defined Data (MDD). Veja [Tabela de MDDs](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | Não | Identificador do chargeback | | `number` | string | Não | Número do chargeback junto à adquirente | | `amount` | number | Não | Valor do chargeback em centavos | | `status` | string | Não | Status do chargeback. Veja [Lista de status do Chargeback](https://docs.payzu.com.br/docs/cartao/transaction-status). Valores: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | Não | Código do motivo informado pela bandeira | | `reasonDescription` | string | Não | Descrição do motivo informado pela bandeira | | `issuedAt` | string | Não | Data de emissão do chargeback | | `createdAt` | string | Não | Data de criação do registro | | `updatedAt` | string | Não | Data da última atualização do registro | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Detalhes do pagamento com cartão de crédito | Campo | Tipo | Obrigatório | Descrição | | ------------------------ | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `installments` | number | Não | Número de parcelas | | `authenticate` | boolean | Não | Indica se o comprador foi direcionado ao emissor para autenticação 3DS | | `currency` | string | Não | Moeda da cobrança. Veja [Moedas](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | Não | Identificador da transação na adquirente | | `authorizationCode` | string | Não | Código de autorização retornado pela adquirente | | `reasonCode` | number | Não | Código do motivo do resultado. Veja [Lista de ReasonCode/ReasonMessage](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | Não | Mensagem do motivo do resultado. Veja [Lista de ReasonCode/ReasonMessage](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | Não | Status da transação. Veja [Lista de status da Transação](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | Não | Código de retorno da adquirente. Veja [Códigos de Erros](https://docs.payzu.com.br/docs/cartao/error-codes) e [Código de retorno ABECS](https://docs.payzu.com.br/docs/cartao/abecs-codes) | | `returnMessage` | string | Não | Mensagem de retorno da adquirente | | `externalAuthentication` | object | Não | Dados da autenticação externa 3DS, quando enviados na criação | | `reversedAmount` | number | Não | Valor estornado em centavos, quando houver estorno | | `reversedDate` | string | Não | Data do estorno, quando houver | | `chargeId` | string | Não | Identificador da cobrança | | `card` | [CardResponse](#cardresponse) | Não | | | `chargebacks` | [Chargeback](#chargeback)\[] | Não | Chargebacks vinculados à cobrança | ## RecurrenceRequest [#recurrencerequest] Configuração de pagamento recorrente. A primeira cobrança é criada na hora; os ciclos seguintes são gerados automaticamente. Exige `installments` igual a 1. Veja [Pagamentos Recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence) | Campo | Tipo | Obrigatório | Descrição | | ---------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- | | `interval` | string | Sim | Intervalo entre as cobranças: `Monthly` (mensal) ou `Annual` (anual). Valores: `Monthly`, `Annual` | | `endDate` | string | Não | Data final da recorrência no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente | ## Recurrence [#recurrence] Estado de uma recorrência | Campo | Tipo | Obrigatório | Descrição | | -------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `recurrentPaymentId` | string | Não | Identificador da recorrência. Use nos endpoints de consulta e gestão de recorrências | | `interval` | string | Não | Intervalo configurado. Valores: `MONTHLY`, `ANNUAL` | | `status` | string | Não | Status da recorrência. Veja [Pagamentos Recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence). Valores: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | Não | Valor de cada ciclo, em centavos | | `nextRecurrency` | string | Não | Data da próxima cobrança automática | | `endDate` | string | Não | Data final, se informada na criação | ## Charge [#charge] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Não | Identificador da cobrança | | `externalId` | string | Não | Identificador único gerado externamente | | `postbackUrl` | string | Não | Url para notificações sobre o status da cobrança | | `amount` | number | Não | Valor da cobrança em centavos | | `paymentType` | string | Não | Tipo de pagamento da cobrança. Veja [Tipos de pagamento](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | Não | Data de criação da cobrança | | `updatedAt` | string | Não | Data da última atualização da cobrança | | `customer` | [CustomerResponse](#customerresponse) | Não | | | `cart` | [CartItem](#cartitem)\[] | Não | Carrinho do comprador | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | Não | | | `recurrence` | [Recurrence](#recurrence) | Não | Presente quando a cobrança pertence a uma recorrência | | `recurrenceCycle` | integer | Não | Número do ciclo da recorrência a que esta cobrança pertence: 0 é a cobrança inicial, 1..n são os ciclos gerados automaticamente. Presente apenas em cobranças de recorrência | ## ChargeRequest [#chargerequest] | Campo | Tipo | Obrigatório | Descrição | | ------------------- | --------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | number | Sim | Valor da cobrança em centavos | | `customer` | [CustomerRequest](#customerrequest) | Sim | | | `postbackUrl` | string | Não | Url para notificações sobre o status da cobrança. Veja [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | Sim | Tipo de pagamento da cobrança. Veja [Tipos de pagamento](https://docs.payzu.com.br/docs/cartao/reference-codes). Valores: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | Sim | Carrinho do comprador | | `creditCardPayment` | object | Sim | Definições para o tipo de pagamento: cartão de crédito | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | Não | | | `externalId` | string | Sim | Identificador único gerado externamente | # 模型 (/docs/cartao/endpoints/models.zh) {/* Gerado por scripts/generate-models.mjs a partir dos specs OpenAPI. Não edite manualmente. */} 下面的模型描述了各端点接受和返回的对象。字段名区分大小写,金额始终以分为单位。 ## Address [#address] Billing address | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | --------------------------- | | `street` | string | 是 | Billing address street | | `number` | string | 是 | Billing address number | | `complement` | string | 否 | Billing address complement | | `zipCode` | string | 是 | Billing address postal code | | `city` | string | 是 | Billing address city | | `state` | string | 是 | Billing address state | | `country` | string | 是 | Billing address country | | `district` | string | 是 | Billing address district | ## CustomerRequest [#customerrequest] Buyer data | 字段 | 类型 | 必填 | 说明 | | -------------- | ------------------- | -- | -------------------------------------- | | `name` | string | 是 | Buyer's full name | | `identity` | string | 否 | Buyer's identification document number | | `identityType` | string | 否 | Buyer's identification document type | | `email` | string | 否 | Buyer's email | | `birthdate` | string | 否 | Buyer's birthdate | | `phone` | string | 否 | Buyer's phone number | | `address` | [Address](#address) | 否 | | ## CustomerResponse [#customerresponse] Buyer data | 字段 | 类型 | 必填 | 说明 | | -------------- | ------ | -- | -------------------------------------- | | `id` | number | 否 | Internal buyer identifier | | `name` | string | 否 | Buyer's full name | | `identity` | string | 否 | Buyer's identification document number | | `identityType` | string | 否 | Buyer's identification document type | | `email` | string | 否 | Buyer's email | | `birthdate` | string | 否 | Buyer's birthdate | | `phone` | string | 否 | Buyer's phone number | | `address` | object | 否 | Billing address | ## CartItem [#cartitem] | 字段 | 类型 | 必填 | 说明 | | ----------- | ------ | -- | -------------------------------- | | `name` | string | 是 | Product name | | `quantity` | number | 是 | Product quantity | | `sku` | string | 是 | Product SKU (Stock Keeping Unit) | | `unitPrice` | number | 是 | Product unit price in cents | ## CardRequest [#cardrequest] Card details | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | --------------------------------------------- | | `number` | string | 是 | Credit card number | | `holder` | string | 是 | Cardholder name as printed on the credit card | | `expiration` | string | 是 | Credit card expiration date | | `cvv` | string | 是 | Security code on the back of the credit card | ## CardResponse [#cardresponse] Details of the card used in the charge | 字段 | 类型 | 必填 | 说明 | | ------------ | ------ | -- | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | 否 | Internal card identifier | | `number` | string | 否 | Credit card number | | `holder` | string | 否 | Cardholder name as printed on the credit card | | `expiration` | string | 否 | Credit card expiration date | | `brand` | string | 否 | Card brand. See [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes). 取值: `Visa`, `Master`, `Elo`, `Diners`, `Hipercard` | ## ExternalAuthentication [#externalauthentication] 3DS authentication data performed outside PayZu (external authentication) | 字段 | 类型 | 必填 | 说明 | | ------------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `cavv` | string | 是 | Signature returned on successful authentication scenarios | | `xid` | string | 否 | XID returned in the authentication process | | `eci` | string | 是 | Electronic Commerce Indicator returned in the authentication process. See [ECI table](https://docs.payzu.com.br/docs/cartao/three-d-secure) | | `version` | string | 是 | 3DS version applied in the authentication process | | `referenceId` | string | 是 | RequestID returned in the authentication process | ## FraudAnalysis [#fraudanalysis] Data for the antifraud engine. Required on international charges. See [Using Antifraud](https://docs.payzu.com.br/docs/cartao/antifraud) | 字段 | 类型 | 必填 | 说明 | | --------------- | --------- | -- | ---------------------------------------------------------------------------------------- | | `fingerPrintId` | string | 是 | Identifier used to correlate information collected from the buyer's device | | `browser` | object | 是 | Information about the buyer's browser | | `definedFields` | object\[] | 是 | Merchant Defined Data (MDD). See [MDD table](https://docs.payzu.com.br/docs/cartao/mdds) | ## Chargeback [#chargeback] | 字段 | 类型 | 必填 | 说明 | | ------------------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | number | 否 | Chargeback identifier | | `number` | string | 否 | Chargeback number at the acquirer | | `amount` | number | 否 | Chargeback amount in cents | | `status` | string | 否 | Chargeback status. See [Chargeback status list](https://docs.payzu.com.br/docs/cartao/transaction-status). 取值: `RECEIVED`, `ACCEPTED`, `DEFENDED` | | `reasonCode` | string | 否 | Reason code provided by the card brand | | `reasonDescription` | string | 否 | Reason description provided by the card brand | | `issuedAt` | string | 否 | Chargeback issue date | | `createdAt` | string | 否 | Record creation date | | `updatedAt` | string | 否 | Date the record was last updated | ## CreditCardPaymentResponse [#creditcardpaymentresponse] Credit card payment details | 字段 | 类型 | 必填 | 说明 | | ------------------------ | ----------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installments` | number | 否 | Number of installments | | `authenticate` | boolean | 否 | Indicates whether the buyer was redirected to the issuer for 3DS authentication | | `currency` | string | 否 | Charge currency. See [Currencies](https://docs.payzu.com.br/docs/cartao/currencies) | | `acquirerTransactionId` | string | 否 | Transaction identifier at the acquirer | | `authorizationCode` | string | 否 | Authorization code returned by the acquirer | | `reasonCode` | number | 否 | Reason code of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `reasonMessage` | string | 否 | Reason message of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `status` | integer | 否 | Transaction status. See [Transaction status list](https://docs.payzu.com.br/docs/cartao/transaction-status) | | `returnCode` | string | 否 | Return code from the acquirer. See [Error Codes](https://docs.payzu.com.br/docs/cartao/error-codes) and [ABECS return codes](https://docs.payzu.com.br/docs/cartao/abecs-codes) | | `returnMessage` | string | 否 | Return message from the acquirer | | `externalAuthentication` | object | 否 | External 3DS authentication data, when sent at creation | | `reversedAmount` | number | 否 | Reversed amount in cents, when a reversal exists | | `reversedDate` | string | 否 | Reversal date, when present | | `chargeId` | string | 否 | Charge identifier | | `card` | [CardResponse](#cardresponse) | 否 | | | `chargebacks` | [Chargeback](#chargeback)\[] | 否 | Chargebacks linked to the charge | ## RecurrenceRequest [#recurrencerequest] Recurring payment configuration. The first charge is created immediately; the following cycles are generated automatically. Requires `installments` equal to 1. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence) | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | ---------------------------------------------------------------------------------------- | | `interval` | string | 是 | Interval between charges: `Monthly` or `Annual`. 取值: `Monthly`, `Annual` | | `endDate` | string | 否 | Recurrence end date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely | ## Recurrence [#recurrence] State of a recurrence | 字段 | 类型 | 必填 | 说明 | | -------------------- | ------ | -- | -------------------------------------------------------------------------------------------------------------------------------- | | `recurrentPaymentId` | string | 否 | Recurrence identifier. Use it on the recurrence query and management endpoints | | `interval` | string | 否 | Configured interval. 取值: `MONTHLY`, `ANNUAL` | | `status` | string | 否 | Recurrence status. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence). 取值: `ACTIVE`, `INACTIVE`, `ENDED` | | `amount` | number | 否 | Amount of each cycle, in cents | | `nextRecurrency` | string | 否 | Date of the next automatic charge | | `endDate` | string | 否 | End date, if provided at creation | ## Charge [#charge] | 字段 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------------------------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | 否 | Charge identifier | | `externalId` | string | 否 | Unique identifier generated externally | | `postbackUrl` | string | 否 | Url for notifications about the charge status | | `amount` | number | 否 | Charge amount in cents | | `paymentType` | string | 否 | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes) | | `createdAt` | string | 否 | Charge creation date | | `updatedAt` | string | 否 | Date the charge was last updated | | `customer` | [CustomerResponse](#customerresponse) | 否 | | | `cart` | [CartItem](#cartitem)\[] | 否 | Buyer's cart | | `creditCardPayment` | [CreditCardPaymentResponse](#creditcardpaymentresponse) | 否 | | | `recurrence` | [Recurrence](#recurrence) | 否 | Present when the charge belongs to a recurrence | | `recurrenceCycle` | integer | 否 | Cycle number of the recurrence this charge belongs to: 0 is the initial charge, 1..n are the automatically generated cycles. Present only on recurrence charges | ## ChargeRequest [#chargerequest] | 字段 | 类型 | 必填 | 说明 | | ------------------- | --------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------- | | `amount` | number | 是 | Charge amount in cents | | `customer` | [CustomerRequest](#customerrequest) | 是 | | | `postbackUrl` | string | 否 | Url for notifications about the charge status. See [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks) | | `paymentType` | string | 是 | Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes). 取值: `creditcard` | | `cart` | [CartItem](#cartitem)\[] | 是 | Buyer's cart | | `creditCardPayment` | object | 是 | Settings for the payment type: credit card | | `recurrence` | [RecurrenceRequest](#recurrencerequest) | 否 | | | `externalId` | string | 是 | Unique identifier generated externally | # Convert amount (/docs/cartao/endpoints/currencies/get_currency_convert.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Converter valor (/docs/cartao/endpoints/currencies/get_currency_convert) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 金额换算 (/docs/cartao/endpoints/currencies/get_currency_convert.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Get currency rate (/docs/cartao/endpoints/currencies/get_currency_rate.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Cotação de moeda (/docs/cartao/endpoints/currencies/get_currency_rate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取汇率 (/docs/cartao/endpoints/currencies/get_currency_rate.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # List currency rates (/docs/cartao/endpoints/currencies/get_currency_rates.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Listar cotações (/docs/cartao/endpoints/currencies/get_currency_rates) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 汇率列表 (/docs/cartao/endpoints/currencies/get_currency_rates.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Get Recurrence (/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Consultar Recorrência (/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询循环扣款 (/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Recurrences (/docs/cartao/endpoints/recurrences/index.en) A recurrence is a subscription: the first charge is created immediately and the following cycles are charged automatically on the card, without a new API call. The recurrence is created in [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) with the `recurrence` node; the endpoints below query and manage the existing subscription. A recurrence is always a single payment: the `installments` field must be `1`. Higher values are rejected. ## Recurrence status [#recurrence-status] | Status | Meaning | | ---------- | ---------------------------------------------------------------------- | | `ACTIVE` | Active, generating cycles at the configured interval. | | `INACTIVE` | Deactivated (manually or by the issuer). Does not generate new cycles. | | `ENDED` | Ended after reaching the `endDate`. | ## Listing the cycles of a subscription [#listing-the-cycles-of-a-subscription] To list the initial charge and all cycles already generated, use [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) with the `recurrentPaymentId` filter: ```bash curl "https://api.payzu.io/v1/charges?recurrentPaymentId={recurrentPaymentId}" \ -H "Authorization: Bearer $TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` Each cycle becomes a charge linked to the recurrence, numbered by `recurrenceCycle` (`0` = initial, `1..n` = cycles). The complete guide to creation, cycles and postbacks is in [Recurring Payments](/docs/cartao/recurrence). # Recorrências (/docs/cartao/endpoints/recurrences) Uma recorrência é uma assinatura: a primeira cobrança é criada na hora e os ciclos seguintes são cobrados automaticamente no cartão, sem nova chamada à API. A recorrência nasce no [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) com o nó `recurrence`; os endpoints abaixo consultam e gerenciam a assinatura já criada. Recorrência é sempre à vista: o campo `installments` precisa ser `1`. Valores maiores são rejeitados. ## Status da recorrência [#status-da-recorrência] | Status | Significado | | ---------- | ---------------------------------------------------------------- | | `ACTIVE` | Ativa, gerando os ciclos no intervalo configurado. | | `INACTIVE` | Desativada (manualmente ou pelo emissor). Não gera novos ciclos. | | `ENDED` | Encerrada por ter atingido a `endDate`. | ## Listar os ciclos de uma assinatura [#listar-os-ciclos-de-uma-assinatura] Para listar a cobrança inicial e todos os ciclos já gerados, use o [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) com o filtro `recurrentPaymentId`: ```bash curl "https://api.payzu.io/v1/charges?recurrentPaymentId={recurrentPaymentId}" \ -H "Authorization: Bearer $TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` Cada ciclo vira uma cobrança vinculada à recorrência, numerada por `recurrenceCycle` (`0` = inicial, `1..n` = ciclos). O guia completo de criação, ciclos e postbacks está em [Pagamentos Recorrentes](/docs/cartao/recurrence). # 循环扣款 (/docs/cartao/endpoints/recurrences/index.zh) 循环扣款就是一份订阅:第一笔收款即时创建,后续周期会自动向卡片扣款,无需再次调用 API。循环扣款在 [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) 中通过 `recurrence` 节点创建;下面的端点用于查询和管理已创建的订阅。 循环扣款必须一次性支付:`installments` 字段必须为 `1`。更大的分期值会被拒绝。 ## 循环扣款状态 [#循环扣款状态] | 状态 | 含义 | | ---------- | ----------------------- | | `ACTIVE` | 已激活,按配置的间隔生成各个周期。 | | `INACTIVE` | 已停用(手动或由发卡行停用)。不再生成新周期。 | | `ENDED` | 已到达 `endDate` 而结束。 | ## 列出订阅的各个周期 [#列出订阅的各个周期] 要列出初始收款和已生成的所有周期,请使用带 `recurrentPaymentId` 筛选的 [`GET /charges`](/docs/cartao/endpoints/charges/get_charges): ```bash curl "https://api.payzu.io/v1/charges?recurrentPaymentId={recurrentPaymentId}" \ -H "Authorization: Bearer $TOKEN" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem ``` 每个周期都会生成一笔关联到该循环扣款的收款,通过 `recurrenceCycle` 编号(`0` = 初始,`1..n` = 后续周期)。 创建、周期与 postback 的完整指南见[循环支付](/docs/cartao/recurrence)。 # Change Recurrence amount (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Alterar valor da Recorrência (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 修改循环扣款金额 (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Deactivate Recurrence (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Desativar Recorrência (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 停用循环扣款 (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Reactivate Recurrence (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Reativar Recorrência (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 重新启用循环扣款 (/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Token (/docs/cartao/endpoints/token/index.en) All charge and recurrence routes require a JWT token in the `Authorization: Bearer` header. This group has a single endpoint, which issues that token from your account credentials. Details about credentials, mTLS and the token lifecycle are in [Authentication](/docs/cartao/authentication). # Token (/docs/cartao/endpoints/token) Todas as rotas de cobrança e recorrência exigem um token JWT no header `Authorization: Bearer`. Este grupo tem um único endpoint, que emite esse token a partir das credenciais da sua conta. Os detalhes das credenciais, do mTLS e do ciclo de vida do token estão em [Autenticação](/docs/cartao/authentication). # Token (/docs/cartao/endpoints/token/index.zh) 所有收款和循环扣款路由都要求在 `Authorization: Bearer` header 中携带 JWT token。本分组只有一个端点,它根据您账户的凭据签发该 token。 凭据、mTLS 和 token 生命周期的详细说明见[身份认证](/docs/cartao/authentication)。 # Get API token (/docs/cartao/endpoints/token/post_token.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Obter token de API (/docs/cartao/endpoints/token/post_token) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 获取 API token (/docs/cartao/endpoints/token/post_token.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # List Charges (/docs/cartao/endpoints/charges/get_charges.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Listar Cobranças (/docs/cartao/endpoints/charges/get_charges) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 收款列表 (/docs/cartao/endpoints/charges/get_charges.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Get Charge (/docs/cartao/endpoints/charges/get_charges__chargeId_.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Consultar Cobrança (/docs/cartao/endpoints/charges/get_charges__chargeId_) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 查询收款 (/docs/cartao/endpoints/charges/get_charges__chargeId_.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Charges (/docs/cartao/endpoints/charges/index.en) Charges are the core of the Card API. You create the charge with the card data, track its status and, if needed, reverse the full or partial amount. ## When to use each one [#when-to-use-each-one] | Question | Endpoint | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | I want to charge a customer's card | [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) | | I need a list of charges, with filters and pagination | [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) | | What is the current state of a specific charge? | [`GET /charges/{chargeId}`](/docs/cartao/endpoints/charges/get_charges__chargeId_) | | I need to refund the money, fully or partially | [`PUT /charges/{chargeId}/reverse`](/docs/cartao/endpoints/charges/put_charges__chargeId__reverse) | The `amount` field is always in cents: `10000` means R$ 100.00. This also applies to the `amount` parameter of the partial reversal. ## Example [#example] The example uses the sandbox and the `4111111111111111` test card; see [Test cards](/docs/cartao/test-cards). ```bash curl -X POST https://api.sandbox.payzu.io/v1/charges \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ -d '{ "amount": 10000, "paymentType": "creditcard", "externalId": "order-1234", "postbackUrl": "https://yoursite.com/webhooks/payzu", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "phone": "11999998888" }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } } }' ``` ## Charge features [#charge-features] The `POST /charges` also accepts variations of the basic flow: # Cobranças (/docs/cartao/endpoints/charges) Cobranças são o núcleo da API de Cartão. Você cria a cobrança com os dados do cartão, acompanha o status e, se precisar, estorna o valor total ou parcial. ## Quando usar cada um [#quando-usar-cada-um] | Pergunta | Endpoint | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Quero cobrar o cartão de um cliente | [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) | | Preciso de uma lista de cobranças, com filtros e paginação | [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) | | Qual o estado atual de uma cobrança específica? | [`GET /charges/{chargeId}`](/docs/cartao/endpoints/charges/get_charges__chargeId_) | | Preciso devolver o dinheiro, total ou parcialmente | [`PUT /charges/{chargeId}/reverse`](/docs/cartao/endpoints/charges/put_charges__chargeId__reverse) | O campo `amount` é sempre em centavos: `10000` significa R$ 100,00. Isso vale também para o parâmetro `amount` do estorno parcial. ## Exemplo [#exemplo] O exemplo usa o sandbox e o cartão de teste `4111111111111111`; veja [Cartões de teste](/docs/cartao/test-cards). ```bash curl -X POST https://api.sandbox.payzu.io/v1/charges \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ -d '{ "amount": 10000, "paymentType": "creditcard", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "phone": "11999998888" }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } } }' ``` ## Recursos da cobrança [#recursos-da-cobrança] O `POST /charges` também aceita variações do fluxo básico: # 收款 (/docs/cartao/endpoints/charges/index.zh) 收款是卡片 API 的核心。您使用卡片数据创建收款,跟踪其状态,需要时对全部或部分金额发起退款。 ## 何时使用哪个端点 [#何时使用哪个端点] | 问题 | 端点 | | -------------- | -------------------------------------------------------------------------------------------------- | | 我想向客户的卡片收款 | [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) | | 我需要带筛选和分页的收款列表 | [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) | | 某笔收款当前是什么状态? | [`GET /charges/{chargeId}`](/docs/cartao/endpoints/charges/get_charges__chargeId_) | | 我需要退还款项,全额或部分 | [`PUT /charges/{chargeId}/reverse`](/docs/cartao/endpoints/charges/put_charges__chargeId__reverse) | `amount` 字段始终以分为单位:`10000` 表示 R$ 100,00。部分退款的 `amount` 参数同样如此。 ## 示例 [#示例] 示例使用 sandbox 环境和测试卡 `4111111111111111`,参见[测试卡](/docs/cartao/test-cards)。 ```bash curl -X POST https://api.sandbox.payzu.io/v1/charges \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ --cert cliente.crt \ --key cliente.key \ --cacert ca.pem \ -d '{ "amount": 10000, "paymentType": "creditcard", "externalId": "order-1234", "postbackUrl": "https://yoursite.com/webhooks/payzu", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "phone": "11999998888" }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } } }' ``` ## 收款的扩展功能 [#收款的扩展功能] `POST /charges` 还支持基础流程之外的变体: # Create Charge (/docs/cartao/endpoints/charges/post_charges.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Criar Cobrança (/docs/cartao/endpoints/charges/post_charges) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 创建收款 (/docs/cartao/endpoints/charges/post_charges.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Reverse Charge (/docs/cartao/endpoints/charges/put_charges__chargeId__reverse.en) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Estornar Cobrança (/docs/cartao/endpoints/charges/put_charges__chargeId__reverse) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # 收款退款 (/docs/cartao/endpoints/charges/put_charges__chargeId__reverse.zh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}