Pagamento White-label (POST/api/v1/Pagamento/gerar-link-white-label)
Fluxo de pagamento Checkout White-Label é o pagamento realizado através do nosso checkout, onde é apresentadopara o cliente uma tela para inserir as informações de pagamento e endereço.
Passo 1: Obter o token de integração (gerado eenviado pela Valorem) e informar no header da requisição.
Passo 2: Gerar o link de pagamento através doendpoint: /api/v1/Pagamento/gerar-link-white-label.
{
"tributo": "string",
"tef": true,
"valor": 0,
"numeroDeParcelas": 0,
"urlRedirecionamento":"string",
"idExterno": "string",
"comprador": {
"nomeComprador":"string",
"cpfcnpjComprador":"string",
"telefone": "string",
"cep": "string",
"logradouro": "string",
"numero": "string",
"bairro": "string",
"cidade": "string",
"uf": "string",
"complemento": "string"
}
}
Passo 3: Inserir dados de pagamento como dados cartão crédito e endereço natela White-label (feito pelo cliente).
Passo 4: Integração gateway de pagamento. Nesse momento o checkout irá receber as informações de pagamento eintegrar com o gateway de pagamento, retornando se houve sucesso ou erro nopagamento. Após o retorno do gateway de pagamento, caso exista cadastrada a urlwebhook na conta bancária, serão enviadas para este webhook as informações datransação e a informação de Status: Confirmado (1), Negado (6), caso atransação tenha sido negada pelo emissor, Expirada (7), Erro na confirmação(8), Falha no pagamento (9). Caso seja necessário, temos status adicionais para informar o inícioda transação, porém aguardando o retorno. Podemos enviar o status do início datransação: Em progresso (5). Realizado por configuração interna.
Exemplo: STATUS [5] EM PROGRESSO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 105.64,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 5,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1/1",
"mensagem": "Aguardando retorno do emissor"
}
]
}
STATUS [1] CONFIRMADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 105.64,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 1,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1/1",
"mensagem": "Pagamento Confirmado"
}
]
}
STATUS [6] NEGADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 6,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela":"1/1",
"mensagem": "Transação foi negada. Resposta:(01 - NotAuthorized) Mensagem: 80 - Unauthorized. Contact issuer. (Insufficientfunds)"
}
]
}
STATUS [7] EXPIRADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 7,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Transação está expirada. Resposta:(09 -Expired) Mensagem: 87 - Expired. Contact issuer. (Timeout payment)"
}
]
}
STATUS [8] ERRO CONFIRMAÇÃO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 8,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": " Transação com erro na confirmação.Resposta:(12 - CONFIRMATION_ERROR) Mensagem: 92 - CONFIRMATION_ERROR. Contactissuer. (Timeout payment)"
}
]
}
STATUS [9] FALHA GSPAYMENTS
{
"registros": [
{
"id_externo":"123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 9,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Houve falha na transação. A transação não foiconcluída."
}
]
}
Passo 5: Na liquidação será realizada atransferência para a conta do estabelecimento e enviaremos na URL webhook ostatus de liquidado.
Exemplo:
{
"registros": [
{
"id_externo": "123T788",
"valor": 112.39,
"valor_original": 105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 3,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1 / 1"
}
]
}
Obs.: Temos uma rotina de reenvio de status caso o webhook não tenhasido enviado por qualquer motivo, para isso precisamos que o response dowebhook tenha o payload abaixo:
{
"ok": bool,
"msg": null
}
Pagamento Transparente (POST/api/v1/Pagamento)
Fluxo de pagamento Checkout Transparente é o pagamento realizado através do seu checkout próprio.
Passo 1: Obter o token de integração (gerado eenviado pela Valorem) e informar no header da requisição.
Passo 2: Inserir dados de pagamento como dadoscartão crédito e endereço através do nosso endpoint: /api/v1/Pagamento.
{
"tributo": "string",
"valor": 0,
"numeroDeParcelas": 0,
"idExterno": "string",
"qtdeCartoes": "Um",
"retornarToken": true,
"cartoes": [
{
"valor": 0,
"numeroDoCartao":"string",
"codigoSeguranca":"string",
"mesVencimento": 0,
"anoVencimento": 0,
"nomeTitular":"string",
"cpfCnpj": "string",
"telefone": "string",
"email": "string",
"cep": "string",
"logradouro":"string",
"numero": "string",
"bairro": "string",
"cidade": "string",
"uf": "string",
"complemento":"string"
}
],
"cartoesTokenizados": [
{
"valor": 0,
"token": "string",
"codigoSeguranca":"string",
"nomeTitular":"string",
"cpfCnpj": "string",
"telefone": "string",
"email": "string",
"cep": "string",
"logradouro":"string",
"numero": "string",
"bairro": "string",
"cidade": "string",
"uf": "string",
"complemento":"string"
}
]
}
Obs.:Ao montar o payload, enviar apenas um dos objetos: cartoesTokenizadosou cartões.Ao marcar oparâmetro [retornarToken] na resposta, irá receber o token do cartão, para queno próximo eventual pagamento com o mesmo cartão possa ser enviado o token parao pagamento sem a necessidade de todos os dados cartão.
Passo 3: Integração gateway de pagamento.
Nesse momento o checkout irá receber as informações de pagamento eintegrar com o gateway de pagamento, retornando se houve sucesso ou erro nopagamento.
Após o retorno do gateway de pagamento, caso exista cadastrada a urlwebhook na conta bancária, serão enviadas para esse webhook as informações datransação e a informação de Status: Confirmado (1), Negado (6) caso a transaçãotenha sido negada pelo emissor, Expirada (7), Erro na confirmação (8), Falha nopagamento (9).
Caso seja necessário temos status adicionais para informar o início datransação, porém aguardando o retorno. Podemos enviar o status do início datransação: Em progresso (5). Realizado por configuração interna.
Exemplo:
STATUS [5] EM PROGRESSO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 105.64,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 5,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1/1",
"mensagem": "Aguardando retorno do emissor"
}
]
}
STATUS [1] CONFIRMADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 105.64,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 1,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1/1",
"mensagem": "Pagamento Confirmado"
}
]
}
STATUS [6] NEGADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 6,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Transação foi negada. Resposta:(01 - NotAuthorized) Mensagem: 80 - Unauthorized. Contact issuer. (Insufficientfunds)"
}
]
}
STATUS [7] EXPIRADO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 7,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Transação está expirada. Resposta:(09 -Expired) Mensagem: 87 - Expired. Contact issuer. (Timeout payment)"
}
]
}
STATUS [8] ERRO CONFIRMAÇÃO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao": "b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 8,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": " Transação comerro na confirmação. Resposta:(12 - CONFIRMATION_ERROR) Mensagem: 92 -CONFIRMATION_ERROR. Contact issuer. (Timeout payment)"
}
]
}
STATUS [9] FALHA GSPAYMENTS
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 9,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Houve falha na transação. A transação não foiconcluída."
}
]
}
Passo 5: Na liquidação será realizada atransferência para a conta do estabelecimento e enviaremos na URL webhook ostatus de liquidado.
Exemplo:
{
"registros": [
{
"id_externo": "123T788",
"valor": 112.39,
"valor_original": 105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 3,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": 1,
"valor_parcela": 105.64,
"parcela": "1 / 1"
}
]
}
Obs.: Temos uma rotina de reenvio de status caso o webhook não tenhasido enviado por qualquer motivo, para isso precisamos que o response dowebhook tenha o payload abaixo:
{
"ok": bool,
"msg": null
}
Estorno do pagamento (POST/api/v1/Pagamento/Cancelamento)
Fluxo de estorno de pagamento é realizadoatravés da nossa API dentro e pode ser enviado no mesmo dia do pagamento.
Passo 1: Obter o token de integração (gerado eenviado pela Valorem) e informar no header da requisição.
Passo 2: Inserir dados de estorno dopagamento: /api/v1/Pagamento/Cancelamento.
{
"IdPagamento": "string"
}
Passo 3: Após o cancelamento será enviado para owebhook cadastrado a notificação de cancelado (4) e após a devolução aocliente será enviado a notificação de reembolso (10).
STATUS [4] CANCELAMENTO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 4,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "", "data_cancelamento": "03/05/2024",
}
]
}
STATUS [10] REMBOLSO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 10,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "O pagamento de R$ 105.64 foi reembolsado.Status: CONFIRMED.",
"data_cancelamento": "03/05/2024"
}
]
}
CONFIRMATION_ERROR [13]
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original": 105.64,
"id_requisicao": "b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 13,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Ocorreu um erro ao tentar reembolsar opagamento de R$ 105.64. Status: CONFIRMATION_ERROR",
"data_cancelamento": null
}
]
}
EXPIRATION [14]
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original": 105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 14,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "A tentativa de reembolso para o pagamento deR$ 105.64 foi expirada. Status: EXPIRATION"
}
]
}
Cancelamento Parcial (POST/api/v1/Pagamento/Cancelamento)
Fluxo de cancelamento de pagamento parcial é realizado através da nossa API dentro e não pode ser enviado nomesmo dia do pagamento.
Passo 1: Obter o token de integração (gerado eenviado pela Valorem) e informar no header da requisição.
Passo 2: Inserir dados de estorno dopagamento: /api/v1/Pagamento/Cancelamento.
{
"IdPagamento": "string",
“valor”: decimal
}
Passo 3: Após o cancelamento será enviado para owebhook cadastrado a notificação de cancelado (4) e após a devolução aocliente será enviado a notificação de reembolso (10).
STATUS [4] CANCELAMENTO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 4,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "",
"data_cancelamento": "03/05/2024",
}
]
}
STATUS [10] REMBOLSO
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original":105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 10,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "O pagamento de R$ 105.64 foi reembolsado.Status: CONFIRMED.",
"data_cancelamento": "03/05/2024"
}
]
}
CONFIRMATION_ERROR [13]
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original": 105.64,
"id_requisicao": "b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 13,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "Ocorreu um erro ao tentar reembolsar opagamento de R$ 105.64. Status: CONFIRMATION_ERROR"
}
]
}
EXPIRATION [14]
{
"registros": [
{
"id_externo": "123TZ788",
"valor": 0,
"valor_original": 105.64,
"id_requisicao":"b4c01b34-9270-405f-8b84-1b5fd5be3103",
"pagamento_id": null,
"status": 14,
"nsus": [
"923025136"
],
"data_credito": "03/05/2024",
"quantidade_cartoes": 1,
"tipo_pagamento": 0,
"quantidade_parcelas": null,
"valor_parcela": null,
"parcela": "1/1",
"mensagem": "A tentativa de reembolso para o pagamento deR$ 105.64 foi expirada. Status: EXPIRATION"
}
]
}
Consulta de transações (GET/api/v1/Pagamento/historico-transacoes)
Fluxo de consulta de transações é possívelconsultar os pagamentos realizados em nossa API informando alguns dados.
Passo 1: Obter o token de integração (gerado eenviado pela Valorem) e informar no header da requisição.
Passo 2: Inserir os filtros da consulta porparâmetros querystring: /api/v1/historico-transacoes.
DataInicio=2024-09-1800:00:00&DataTermino=2024-09-1812:00:00&TamanhoDaPagina=100&NumeroDaPagina=0
Modelo da Resposta:
{
"success": true,
"data": {
"pagamentoId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pagamentoPaiId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"dataCriacao":"2024-10-01T15:00:01.291Z",
"dataAlteracao":"2024-10-01T15:00:01.291Z",
"dataPagamento":"2024-10-01T15:00:01.291Z",
"tributo": "string",
"realizarAntecipacaoPagamento":true,
"realizarCalculo": true,
"cpfCnpj": "string",
"nome": "string",
"valor": 0,
"valorOriginal": 0,
"numeroDeParcelas": 0,
"formaPagamento":"string",
"statusPagamento":"string",
"urlWebhook": "string",
"linkPagamento":"string",
"urlRedirecionamento":"string",
"jsonRequisicao":"string",
"jsonResposta":"string",
"tipoPagamento":"WhiteLabel",
"quantidadeCartoes":"Um",
"portal": "string",
"estabelecimento": {
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"cpfCnpj": "string",
"nomeFantasia":"string",
"parceiroComercial":"string"
},
"contaBancaria": {
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"favorecido":"string",
"cpfCnpj": "string",
"banco": "string",
"tipoConta":"ContaPoupanca",
"agencia": "string",
"digitoAgencia":"string",
"conta": "string",
"digitoConta":"string",
"ativo": true,
"orgaoPublico": true,
"nome": "string",
"taxa": 0,
"webHookUrl":"string",
"convenio": "string"
},
"transacao": {
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"bandeira": "string",
"clienteId":"string",
"transacaoCodigo": 0,
"transacaoMensagem":"string",
"valor": 0,
"nit": "string",
"terminalId":"string",
"nsuHost": "string",
"codigoAutorizacao":"string",
"acquirerId":"string",
"dataPagamento":"2024-10-01T15:00:01.291Z",
"jsonRequisicao":"string",
"jsonResposta":"string",
"jsonTefRecebido":"string",
"nsuPreAutorization":"string",
"gti": "string"
},
"cobranca": {
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nome": "string",
"cpfcnpj": "string",
"cep": "string",
"logradouro":"string",
"numero": "string",
"bairro": "string",
"cidade": "string",
"uf": "string",
"telefone": "string",
"complemento":"string"
},
"antecipacao": [
{
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pagamentoId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"dataTransacao":"2024-10-01T15:00:01.291Z",
"dataAntecipacao":"2024-10-01T15:00:01.291Z",
"dataVencimento":"2024-10-01T15:00:01.291Z",
"numeroParcela": 0,
"valorParcela": 0,
"valorTaxaProcessamento": 0,
"valorLiquido": 0,
"diasAntecipados": 0,
"valorTaxaAntecipacao": 0,
"valorLiquidoAntecipado": 0
}
],
"numeroSequencial":"string"
}
}
Tokenizar cartão de crédito (POST/api/v1/Pagamento/tokenizar)
Fluxo para retornar os dados tokenizados para eventuais futuras compras sem a necessidade de informar todos os dados doscartões.
Passo1: Obter o token de integração(gerado e enviado pela Valorem) e informar no header da requisição.
Passo 2: Inserir dados do cartão crédito atravésdo nosso endpoint: /api/v1/Pagamento/tokenizar.
{
"cnpjEstabelecimento":"string", (cnpj do estabelecimento)
"identificadorCliente":"string", (cpf ou cnpj do cliente)
"card": {
"numeroDoCartao":"string",
"mesVencimento":"string",
"anoVencimento":"string"
}
}
Cartões de testes da Rede
BANDEIRA TIPO NÚMERO VALIDADE SECURITY CODE
Mastercard Crédito 5448280000000007 01/28 123
VisaCredito Crédito 4235647728025682 01/28 123
Mastercard Crédito 2223020000000005 01/28 123
Cartão de teste demais
BANDEIRA TIPO NÚMERO VALIDADE SECURITY CODE
VisaCredito Crédito 4111111111111111 12/34 123
