• Home
  • Documentação

Zukese Pay – E-commerce API (v1.0)

Este documento direciona ao desenvolvedor a correta utilização de integração das APIs no WordPress

Introdução

As APIs do ZukesePay foram desenvolvidas em REST. As URL seguem o padrão do mercado para facilitar a integração dos serviços, utilizando o protocolo HTTP. Todas as respostas são retornados no formato JSON.

A atual versão do ZukesePay REST API é v1.

O fluxo de comunicação utiliza tokens específicos para autenticação, conforme a tabela abaixo:

HeaderFluxo
X-ZukesePay-TokenE-Commerce > ZukesePay
X-ZukesePay-Seller-TokenZukesePay > E-Commerce

Ambos os tokens serão fornecidos pelo ZukesePay após o cadastro da loja no aplicativo.

As APIs estão organizadas em 3 requisições:

  1. Requisição de pedido;
  2. Status do pedido;
  3. Cancelamento do pedido;

Formato da API

Todos as requisições devem seguir as regras abaixo:

Cabeçalhos de requisição

Todas as requisições deverão conter o cabeçalho Content-Type: application/json presentes.

Corpo da requisição

O corpo da requisição sempre deverá apresentar o formato JSON no conteúdo das requisições.

Lista de endpoints

AmbienteEndereço
Produçãohttps://painel.zukesepay.com
HomologaçãoIndisponível

Referência da API

Requisição de checkout

Inicia a solicitação de pagamento para o ZukesePay. Após a requisição ao endpoint, o cliente deverá redirecionado para o endereço informado no campo payment_url para que o cliente possa realizar o pagamento

Endereço:

POST api/v1/ecommerce/public/payments

Cabeçalhos:

x-zukesepay-token: ""

Corpo da requisição:

{
	"order_id": "ZUKPAY-1",
	"callback_url": "https://www.loja.com/callbackurl",
	"return_url": "https://www.loja.com/pedido/checkout/1234",
	"value": 99.99,
	"expires_at": "2022-01-01T16:00:00+03:00",
	"buyer_first_name": "Lorem",
	"buyer_last_name": "Ipsum",
	"buyer_document": "191.000.000-00",
	"buyer_email": "lorem@zukesepay.com",
	"buyer_phone": "244226434543"
}

Descrição:

  • order_id ( String ): Identificador único do pedido. Este campo precisa de um valor diferente a cada requisição. Ele será exibido ao cliente no momento de pagamento e também é utilizado para efetuar cancelamento, ver status do pedido, etc
  • callback_url ( String ): Url onde o ZukesePay enviará o status do pedido
  • return_url ( String ): Url onde o usuário será redirecionado após o pagamento
  • value ( Double ): Valor do pagamento em Kwanza
  • expires_at ( Datetime ): Data de expiração do pagamento. Formato ISO 8601
  • buyer_first_name ( String ): Primeiro nome do comprador
  • buyer_last_name ( String ): Sobrenome do comprador
  • buyer_document ( String ): Documento do comprador
  • buyer_email ( String ): E-mail do comprador
  • buyer_phone ( String ): Número de telefone do comprador

Respostas:

HTTP 200:
{
    "order_id": "ZUKPAY-1",
    "payment_url": "https://zukesepay.com/checkout/RGVidDoxMTI=",
    "expires_at": "2022-01-01T14:00:00+01:00"
}
Descrição:
  • order_id ( String ): Identificador único do pedido.
  • payment_url ( String ): URL onde a loja deverá redirecionar o usuário para a conclusão do pagamento
  • expires_at ( Datetime ): Data de expiração dessa URL de pagamento
HTTP 401: Token de autenticação inválido
{
    "message": "string"
}
Descrição:
  • message ( String ): Mensagem de erro
HTTP 422: Foram encontrados erros ao validar os dados
{
    "message": "string",
    "errors": array
}
Descrição:
  • message ( String ): Mensagem de erro sobre a falha na validação.
  • errors ( array ): Lista de items contendo os erros de validação encontrados.
HTTP 500: Erro interno no servidor
{
    "message": "string"
}
Descrição:
  • message ( String ): Mensagem de erro sobre a falha no servidor ao processar a solicitação.

Status do pagamento

Consulta o status de pagamento do pedido solicitado a ZukesePay

Endereço:

POST api/v1/ecommerce/public/payments/{order_id}/status

Cabeçalhos:

x-zukesepay-token: ""

Corpo da requisição:

{
	"order_id": "ZUKPAY-1",
}

Descrição:

  • order_id ( String ): Identificador único do pedido realizado anteriormente.

Respostas:

HTTP 200:
{
    "order_id": "ZUKPAY-1",
    "status": "Concluida"
}
Descrição:
  • order_id ( String ): Identificador único do pedido.
  • status ( String ): Status do pedido. O status do pedido pode ser um dos status abaixo:
    • Concluida: Pagamento concluído;
    • Em analise: Pagamento efetuado, aguardando ação de avaliação manual;
    • Cancelado: Pagamento cancelado;
    • Reembolsado: Pagamento reembolsado pelo lojista;
    • Ressarcido: Pagamento reembolsado pela instituição financeira;
HTTP 401: Token de autenticação inválido
{
    "message": "string"
}
Descrição:
  • message ( String ): Mensagem de erro
HTTP 422: Foram encontrados erros ao validar os dados
{
    "message": "string",
    "errors": array
}
Descrição:
  • message ( String ): Mensagem de erro sobre a falha na validação.
  • errors ( array ): Lista de items contendo os erros de validação encontrados.
HTTP 500: Erro interno no servidor
{
    "message": "string"
}
Descrição:
  • message ( String ): Mensagem de erro sobre a falha no servidor ao processar a solicitação.

Cancelamento do pedido

Solicite o cancelamento/estorno de um pedido. O cancelamento do pagamento está sujeito a seguinte regras (além de quaisquer termos e/outras regulações existentes):

  1. Se o pagamento foi já foi efetivado, o valor será estornado se sua conta de Lojista no ZukesePay tenha saldo para realizar o estorno, caso o cliente ZukesePay que efetuou o pagamento tenha recebido algum cashback nesta transação, este valor será estornado do cliente (para isto o mesmo deve possuir saldo). Todos esses requisitos devem ser cumpridos para que o estorno da transação ocorra com sucesso;
  2. Se o pagamento ainda não foi realizado, a transação será cancelada no sistema de pagamentos e outro código de pagamento deverá ser gerado;

Endereço:

POST api/v1/ecommerce/public/payments/{order_id}/cancellations

Cabeçalhos:

x-zukesepay-token: ""

Corpo da requisição:

{
    "order_id": "ZUKPAY-1",
}

Descrição:

  • order_id ( String ): Identificador único do pedido realizado anteriormente.

Respostas:

HTTP 200:
{
    "order_id": "ZUKPAY-1"
}
Descrição:
  • order_id ( String ): Identificador único do pedido.
HTTP 401: Token de autenticação inválido
Descrição:
  • message ( String ): Mensagem de erro
HTTP 422: Foram encontrados erros ao validar os dados
Descrição:
  • message ( String ): Mensagem de erro sobre a falha na validação.
  • errors ( array ): Lista de items contendo os erros de validação encontrados.
HTTP 500: Erro interno no servidor
Descrição:
  • message ( String ): Mensagem de erro sobre a falha no servidor ao processar a solicitação.

Notificações

Enviaremos uma notificação para sua loja caso algum desses eventos ocorram:

  1. Pagamento efetuado;
  2. Pagamento cancelado;

Notificaremos para a url fornecida no campo callback_url, via POST, informando que houve alteração no status do pedido.

O status do pedido não será informado nessa requisição. Para isso, a loja deverá consultar o endpoint de Status do pedido

Pagamentos e compras a partir do seu telemóvel