Split de pagamento para plataformas

Neste guia você vai aprender a cadastrar um aplicativo representando sua empresa ou plataforma para solicitar acesso à conta de outros estabelecimentos.

Com isso você pode realizar transações em nome de outros estabelecimentos, adicionar suas taxas e o split do pagamento é feito automaticamente para as contas bancárias de cada envolvido na transação.

Você vai precisar de uma conta Gen Business para cadastrar sua aplicação, caso ainda não tenha criado sua conta, confira o passo a passo neste link. Cada usuário que conceder acesso a sua plataforma também precisa estar cadastrado na Gen Business como um estabelecimento, você pode redirecionar ele para nossa tela de cadastro neste link

Cadastrando um aplicativo

Para cadastrar um novo aplicativo entre na plataforma web, acesse sua conta em ambiente de sandbox , vá no menu lateral esquerdo, clique em Configurações -> Desenvolvedor -> Aplicativos > + Cadastrar Novo e informe os seguintes dados:

• Nome: Nome do aplicativo para as pessoas reconhecerem sua aplicação
• URL de redirecionamento: URL para onde redirecionar os usuários após eles autorizarem seu aplicativo.
• Logo: Uma imagem ou logo para ajudar a reconhecer sua aplicação ou empresa.

Depois de criar o aplicativo, você vai utilizar o ID e a Chave (Secret) para gerar uma chave de acesso da conta do estabelecimento.

Solicitando o acesso ao usuário

Redirecione o usuário para a página de autorização utilizando a url abaixo e preenchendo com as informações do seu aplicativo:

• client_id (ID APLICATIVO): O id do aplicativo criado.
• redirect_uri (URL REDIRECIONAMENTO): URL para onde redirecionar os usuários após eles autorizarem seu aplicativo. Deve ser igual à URL informada no cadastro do app.
• response_type: Constante, igual a code.

Referência da API: Solicitar Acesso

// Ambiente sandbox

"https://api-dev.genpag.com.br/oauth/authorize?client_id=(ID APLICATIVO)&response_type=code&redirect_uri=(URL REDEDIRECIONAMENTO)"

// Ambiente de produção

"https://api.genpag.com.br/oauth/authorize?client_id=(ID APLICATIVO)&response_type=code&redirect_uri=(URL REDIRECIONAMENTO)"

Caso o usuário aceite a solicitação e autorize sua aplicação, ele será redirecionado para URL que você informou no cadastro do app com um parâmetro code ?code=authorization_code.

Utilize esse parâmetro para gerar uma chave de acesso da conta do usuário. Envie uma requisição POST para o endpoint da API /oauth/token com os seguintes dados no corpo da requisição:

• client_id: O ID do seu aplicativo;
• client_secret: A chave de acesso do seu aplicativo
• grant_type: Utilize o valor fixo authorization_code;
• code: O código recebido via redirecionamento após a autorização do usuário;
• redirect_uri: URL de redirecionamento utilizada.

Atenção:

Faça essa requisição para gerar a chave de acesso a partir do seu servidor e guarde com cuidado. As credenciais geradas não são adequadas para serem manipuladas através do navegador.

Referência API: Gerar Token

curl -X POST 'https://api-dev.genpag.com.br/oauth/token' \

        -H 'Content-Type: application/json' \

        --data '{

            "client_id": "465706b0-5fea-4496-8e8f-b8cedcd1bb6a",

            "client_secret": "EBACE73F2A682AAB3EE0FE3E5D040B770DD0EE886A19F055A513D87F569A2EEA",

            "grant_type": "authorization_code",

            "code": "SFMyNTY.g2gDdAAAAANkAAljbGllbnRfaWRtAAAAJDVhNzlmOWM0LTdkOWYtNDQ3ZC1iYTk2LWVkMDkwMDkxYWU0OGQAC3Jlc291cmNlX2lkbQAAACRkNjUyOGJiOC1iN2MwLTQ0YWYtOTdiZC01OTBhYjNmYzI0ZmFkAAZzY29wZXNtAAAACnJlYWQsd3JpdGVuBgCyiPfjeQFiAAFRgA.mys2Jxzw_WbYxBi9yOsfcX7wTZpbqhKIHgXn97aeUGQ",

            "redirect_uri": "https://minhaempresa.com.br/oauth/callback"

        }'

A resposta dessa solicitação, caso ocorra com sucesso, será um objeto com os seguintes dados:

{

  "access_token": //A chave de acesso para a conta do usuário;

  "refresh_token": //A chave de atualização para gerar uma nova chave de acesso;

  "expires_in": //Validade da chave em segundos;

  "token_type": //Tipo de chave;

  "profile": { //Dados da conta do usuário:

    "user_id": //ID do usuário

    "seller_id": //ID do cadastro de vendedor do usuário, se houver

    "customer_id": //ID do cadastro cliente do usuário, se houver

  }

}

Atualizando a chave de acesso

A chave de acesso gerada no passo anterior tem a validade de 1 semana. Depois disso, você precisa utilizar a chave de atualização (refresh token) que você recebeu na solicitação anterior para gerar uma nova chave de acesso.

Referência API: Gerar Token

curl -X POST 'https://api-dev.genpag.com.br/oauth/token' \

        -H 'Content-Type: application/json' \

        --data '{

            "client_id": "465706b0-5fea-4496-8e8f-b8cedcd1bb6a",

            "client_secret": "EBACE73F2A682AAB3EE0FE3E5D040B770DD0EE886A19F055A513D87F569A2EEA",

            "grant_type": "refresh_token",

            "refresh_token": "SFMyNTY.g2gDdAAAAANkAAljbGllbnRfaWRtAAAAJDVhNzlmOWM0LTdkOWYtNDQ3ZC1iYTk2LWVkMDkwMDkxYWU0OGQAC3Jlc291cmNlX2lkbQAAACRkNjUyOGJiOC1iN2MwLTQ0YWYtOTdiZC01OTBhYjNmYzI0ZmFkAAZzY29wZXNtAAAACnJlYWQsd3JpdGVuBgCyiPfjeQFiAAFRgA.mys2Jxzw_WbYxBi9yOsfcX7wTZpbqhKIHgXn97aeUGQ",

            "https://minhaempresa.com.br/oauth/callback"

A resposta dessa solicitação, caso ocorra com sucesso, será um objeto com os seguintes dados:

{

  "access_token": //A chave de acesso para a conta do usuário;

  "refresh_token": //A chave de atualização para gerar uma nova chave de acesso;

  "expires_in": //Validade da chave em segundos;

  "token_type": //Tipo de chave;

  "profile": { //Dados da conta do usuário:

    "user_id": //ID do usuário

    "seller_id": //ID do cadastro de vendedor do usuário, se houver

    "customer_id": //ID do cadastro cliente do usuário, se houver

  }

}

Gerando um pedido com a chave obtida

Depois de gerar as chaves de acesso à conta do usuário, você pode começar a criar pedidos e pagamentos em nome do estabelecimento dele e adicionar suas taxas ao pedido.

Quando o pedido for pago, seja pela nossa página de checkout ou pela sua interface, você receberá na sua conta bancária cadastrada o valor referente a taxa da sua plataforma e o estabelecimento do seu usuário receberá os valores na conta dele.

Para cadastrar um pedido, envie requisição POST conforme os parâmetros abaixo para o endpoint /api/sellers/:sellerId/orders:

Referência da API: Criar Pedido

curl -X POST 'https://api-dev.genpag.com.br/api/sellers/:sellerId/orders' \

--header 'Authorization: Bearer <access_token>'

--header 'Content-Type: application/json' \

--data-raw '{

    "order": {

        "items": [

            {

                "description": "tempor anim",

                "quantity": 1,

                "unit_price_cents": 4498,

            },

            {

                "description": "veniam co",

                "quantity": 1,

                "unit_price_cents": 5000,

            }

        ],

        "fee_percent": 10.0,

        "fee_amount_cents": 1000 //Substitui o fee_percent

    }

}'

O parâmetro :sellerId da URL é o ID do estabelecimento do usuário. Você recebeu esse id no momento em que gerou as chaves de acesso da conta no campo profile.

Os campos fee_percent e fee_amount_cents são utilizados para informar a taxa total a ser cobrada do seu cliente. Você pode cobrar um valor percentual sobre o valor total da operação ou um valor fixo em centavos.

Atenção

Se informado, o valor da taxa é total e deve incluir as taxas da Gen Pag, se for menor você receberá um erro ao tentar criar o pedido. Os valores de taxas em homologação são ilustrativos e não refletem as taxas negociadas para sua conta em produção, consulte as condições do seu contrato para verificar as taxas.

Se a requisição acima resultar em sucesso, você receberá como resposta um objeto contendo os dados do pedido:

{

   "data": {

        "id": "6d4476d7-542a-543b-81ca-966618b9f48a",

        "seller_id": "72e0e63b-1323-17a4-e8a3-6df8ae93f352",

        "marketplace_id": "d411aaf0-329a-6f29-8443-ba0422223b67",

        "items": [

            {

                "description": "tempor anim",

                "quantity": 1,

                "unit_price_cents": 4498,

            },

            {

                "description": "veniam co",

                "quantity": 1,

                "unit_price_cents": 5000,

            }

        ],

        "fee_percent": 10.0,

        "customer_id": null,

        "subtotal_cents": 9498,

        "discount_cents": 0,

        "addition_cents": 0,

        "shipping_cents": 0,

        "total_cents": 9498,

        "status": "PENDING",

        "external_id": null,

        "location": { },

        "customer_data": { },

        "shipping_address": { },

        "subscription_id": null,

        "inserted_at": "1966-05-05T00:33:17.927Z",

        "updated_at": "2009-04-07T12:26:30.452Z"

   }

}

Agora é só utilizar o :id do pedido para gerar o link da página de checkout, ou passar como um parâmetro na criação do pagamento, caso esteja fazendo sua própria interface de checkout.

Página de Checkout

Após criar o pedido, redirecione o usuário final para a página de checkout seguindo o padrão de URL a seguir:

// Ambiente de homologação

// https://app-dev.genpag.com.br/orders/:id?redirectTo=<sua_url>

"https://app-dev.genpag.com.br/orders/6d4476d7-542a-543b-81ca-966618b9f48a?redirectTo=https://example.com"

// Ambiente de produção

// https://app.genpag.com.br/orders/:id?redirectTo=<sua_url>

"https://app.genpag.com.br/orders/6d4476d7-542a-543b-81ca-966618b9f48a?redirectTo=https://example.com"

No campo :id utilize o id do pedido gerado anteriormente e o usuário final irá acessar a interface de checkout.

Se o cliente abrir a url em um dispositivo mobile, ele será redirecionado para nosso checkout smartPOS responsivo:

Caso você informe uma URL de redirecionamento (redirectTo) o usuário será redirecionado para seu sistema após a confirmação do pagamento.