Global Pays - Manual API

Sobre a documentação

Esta documentação tem como objetivo instruir a implementação da API de pagamentos Global Pays Para realizar a integração com o gateway de pagamentos da Global Pays é necessário um programador com conhecimentos básicos em comunicação REST e manipulação de arquivos Json.

Autenticação

A autenticação é feita através do fornecimento de seu Token. Ele deve ser transmitido em todas as requisições no header token. Caso o Token seja inválido ou não seja informado, a API retornará HTTP 401.

Os Tokens são distintos entre os ambientes de Sandbox e Produção, portanto lembre-se de alterá-lo quando mudar a URL.

Códigos HTTP das respostas

A Global Pays utiliza respostas HTTP convencionais para indicar sucesso ou falha nas requisições. Respostas com status 200 indicam sucesso, status 4xx indicam falhas decorrentes de erros nas informações enviadas, e status 500 indicam erros internos no servidor da Global Pays.

Código HTTP Descrição
200 OK Sua requisição foi bem sucedida.
300 The pubKey was not informed.
310 The merchantCode was not informed.
320 Invalid credentials.
330 Merchant account not found.
340 The amount entered must be equal to or greater than 1.
350 Callback redirection routes not informed.
360 There was an error calculating the values, if the error persists, please contact support
370 An error occurred when registering the order, if the error persists contact support.
380 Order id not entered or not numeric.
390 Merchant account not found.
400 Order not found.
410 Invalid token.
420 Expired token.

Todos os endpoints da Global Pays recebem e respondem em JSON.

Exemplo de resposta para HTTP 300:


{
    "statusCode":300,
    "statusType":"error",
    "msg":"The pubKey field is required"
}

Ambiente de desenvolvimento e testes

Produção Sandbox
https://api.tryglobalpays.com/v1 https://apihml.tryglobalpays.com/v1

Cartão e crédito para testes

Bandeira: Visa

Número do cartao: 4111111111111111

CVV: 123

Validade: 10/2040

Autenticação

Solicitar Token de acesso

Para gerar seu Token, você deve fazer um requisição usando o seu pubKey, gerado no seu ambiente Sandbox. Você deverá usar seu Token em todas as outras requisições em nossa API.

Transações

Os status possíveis de uma transação são os seguintes:

open - Transação está aberta para pagamento (ainda não teve interação do cliente).

pending - O cliente gerou um boleto e a transação está aguardando a quitação do mesmo

analysis - Pagamento efetuado mas está em análise para liberação pelo setor de segurança, (este status não significa que a compra está concluída, pois pode não ser aprovada pelo setor de segurança caso seja identificada alguma inconsistência nos dados).

approved - Pagamento efetuado e liberado pelo setor de segurança, (este status significa que a compra está totalmente liberado e será transferido para a conta bancária do merchant registrada em nosso sistema).

delivered - A compra está totalmente liberada e já foi transferida para a conta bancária do merchant registrada em nosso sistema.

canceled - Pagamento efetivado mas cancelado posteriormente à pedido do cliente ou por não atender aos requisitos de segurança.

aborted - A transação foi abortada antes de sua conclusão(ocorre quando o cliente clica no botão cancelar na tela de pagamento).

Criar nova transações

Para realizar a criação de transações é necessário que já tenha sido gerado um TOKEN de acesso, e este deve ser enviado através do header da requisição com Bearer Token

Split de comissão (commissionSplit) : Caso deseje acrescer um valor de comissão ao valor original da compra para que seja dividido entre outros merchants. obrigatoriamente a soma das comissões já devem estar acrescidas ao valor amount principal, pois esta comissão é subtraída do valor a ser repassado para o merchant principal.

Rota de Callback (callback) : A rota de callback é utilizada para redirecionar o cliente pagador para seu ambiente, será adicionado a ela um parâmetro após o endereço fornecido que é o orderId(Id da ordem que está sendo processada) ficando assim: https://SEUHOST/seuendpoint?orderId=1234.
OBS: Nesse endereço você deve realizar uma consulta para nossa api seguindo a instrução que está no tópco "CONSULTAR UMA TRANSAÇÃO", para confirmar se a transação está paga ou foi cancelada, só então direcionar seu cliente para sua tela de sucesso ou cancelamento.

Consultar uma transação

Para recuperar uma transação específica é necessário que você tenha o ID (orderId) que a Global Pays retornou no momento da criação dela.

Inativando uma transação

Para inativar uma transação específica é necessário que você tenha o ID (orderId) que a Global Pays retornou no momento da criação dela.

Consultando valores

Calcular novo valor

Para calcular o valor total de taxas, impostos e valor total a pagar. Nossa API irá retornar os totais por forma de pagamento, PIX, Boleto e cartão de crédito.

Webhooks

O sistema irá enviar notificações HTTP POST para a URL cadastrada na tela de integração na dashboard onde é gerada a chave de integração. As notificações são enviadas somente para as transações criadas a partir da API. Quando o status de uma transação for alterado, você receberá uma requisição na rota cadastrada contendo o conteúdo semelhante ao exemplo abaixo:

Para cadastrar uma rota de webhook, efetue login em sua conta na Global Pays, no menu lateral vá em integrações, nesta tela você pode gerar sua chave de integração, uma vez gerada a chave você verá opções de integração, como está realizando uma integração própria, ative a opção geral e insira sua rota de webhook no campo que irá aparecer.

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:


{
    "orderId": 15613,
    "order_date": "2023-02-15 12:11:37",
    "payment_date": "2023-02-15 19:27:18",
    "amount": 598.96,
    "invoice": "Invoice text",
    "description": "",
    "authCode": "99999999999999",
    "payment_method": "Cartão de Crédito",
    "total_amount_usd": 678.32,
    "total_amount_brl": 3833.12,
    "installment": 6,
    "status": "approved",
    "client": {
        "name": "Naruto Uzumaki",
        "email": "rgda@seudominio.com",
        "doc": "9999999999",
        "phone": "99999999999",
        "cep": "99999999",
        "address": "Rua",
        "numberAddress": "1",
        "district": "Bairro",
        "city": "Cidade",
        "state": "UF"
    },
    "last_update": "2020-02-15 19:27:18",
    "url_checkout": ""
}