Autenticação

Para fazer um pagamento usando qualquer uma das operações da API do Ripple Payments, você precisa de um token de acesso válido.

Esse token de acesso é exigido por todas as operações da API do Ripple Payments (exceto a própria operação de autenticação). Você precisa incluir um token de acesso válido no cabeçalho Authorization de cada requisição.

Ripple Payments oferece um modelo seguro de autenticação e autorização, fornecendo tokens de acesso com escopo definido para um conjunto de credenciais.

A operação de autenticação retorna um token de acesso no campo de resposta access_token. Você precisa incluir o seu client_id e o seu client_secret no corpo JSON para obter um token de acesso válido.

Você precisa do seu client ID e do seu client secret para obter um token de acesso.

Se você ainda não tem o seu client ID e client secret, faça o seguinte:

1. Faça login no Ripple Payments.
2. No canto superior direito da página, clique no ícone de engrenagem Configurações.
3. Em Integração, selecione Credenciais de API.
4. No canto superior direito da página, selecione o ambiente de acesso na lista suspensa. Por exemplo, para provisionar credenciais do ambiente UAT, selecione UAT na lista suspensa.
5. No canto superior direito da página, clique em Nova credencial.
6. No campo Nome da credencial, informe um nome para a credencial.
7. Clique em Salvar e gerar chave.

Agora você pode usar o client ID e o client secret para gerar tokens de acesso pela operação de autenticação.

Recomendamos rotacionar as suas credenciais de API em intervalos regulares, conforme a política de segurança da sua organização.

Assim que tiver o seu client ID e o seu client secret, siga estas etapas para obter um token de acesso que você possa usar nas chamadas da API do Ripple Payments:

A primeira etapa para obter um token de acesso é determinar o ambiente que você quer acessar.

A tabela a seguir descreve as diferenças de tipos de parceiros e de moeda nos ambientes que dão acesso à API do Ripple Payments. Anote a string de ambiente do ambiente que você quer acessar.

O formato de uma requisição de autenticação é o seguinte:

POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
   "grant_type":"client_credentials",
   "client_id":"{YOUR_CLIENT_ID}",
   "client_secret":"{YOUR_CLIENT_SECRET}",
   "audience": "urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}"
}

Os valores esperados são os seguintes:

Exemplos:

Exemplo de requisição (sucesso no ambiente de produção) – uma requisição bem-sucedida a um ambiente de produção pode ser parecida com o exemplo a seguir:

POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
    "grant_type": "client_credentials",
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}"
}

Exemplo de resposta (sucesso no ambiente de produção) – uma requisição bem-sucedida retorna uma resposta parecida com o exemplo a seguir:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "keys:read keys:write payments:create quotes:create identities:create audit:read"
}

Use o endpoint /oauth/token/test para verificar a validade do seu token de acesso em um ambiente Ripple específico e descobrir quanto tempo resta até ele expirar.

Este exemplo demonstra como usar o endpoint /oauth/token/test para testar um token de acesso.

Aqui, aplicamos o token de acesso eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ ao cabeçalho Authorization: Bearer.

GET https://api.ripple.com/v2/oauth/token/test
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

A resposta é um objeto JSON com as seguintes propriedades:

• message : indica o status do token de acesso.
• seconds_to_expiry : representa o número de segundos restantes até o token de acesso expirar.

{
"message": "token_ok",
"seconds_to_expiry": 3600
}

Ripple Payments usa Bearer Token Authorization em todas as operações (exceto a própria operação de autenticação). Para fazer requisições bem-sucedidas à API do Ripple Payments, inclua um token de acesso válido no cabeçalho Authorization de cada requisição, no seguinte formato:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

Para usar isso em uma requisição de API, adicione o valor do campo access_token ao cabeçalho Authorization em todas as operações da API do Ripple Payments (exceto a própria operação de autenticação). Lembre-se de acrescentar Bearer (incluindo um espaço) antes do token de acesso.

Por exemplo:

GET https://api.ripple.com/v2/payments/{YOUR_PAYMENT_ID}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

Se uma requisição de token falhar, o corpo da resposta usa o formato no estilo OAuth, com os campos error e error_description, em vez do formato padrão de erro de pagamento. A tabela a seguir lista as respostas que você pode receber:

Baseie o seu tratamento de erros no código de status HTTP, e não na string error, e trate qualquer 403 como uma falha de autorização que não deve ter nova tentativa. Tentar novamente com as mesmas credenciais produz o mesmo resultado.

Os tokens de acesso são válidos por 1 hora. Depois que você obtém um novo token, ele fica em cache por um tempo limitado. Para evitar problemas causados por cache duplo, não armazene o token em cache no cliente. Se você armazenar o token em cache, precisa limpar o cache dentro do período especificado pelo campo expires_in (conforme a claim exp do JWT) no corpo da resposta.

Payments Direct não oferece suporte a listas de IPs permitidos. A API do Payments Direct foi projetada para acesso aberto pela internet pública, protegida por credenciais de cliente OAuth2 e autorização por Bearer token, e não por restrições de IP em nível de rede.