Introduction

Documentação da API Adquirência para vendas e-commerce com cartão de crédito/débito.

Tabela de Erros da Aplicação

Estes são alguns dos possíveis erros retornados da API Adquirência. Todos os erros abaixo possuem o HTTP Status Code 500.

Código do Erro	Mensagem
INVALID_CVV	Invalid CVV. CVV should be 3 digits.
INVALID_MONTH_NUMBER	Incorrect expiration date. Invalid month number.
AMOUNT_MISMATCH	General error.
MSG_GENERAL_ERROR	Unknown Card Brand.
MSG_AUTHORIZATION_TOKEN_NOT_VALID	Não foi possível processar a venda.
AMOUNT_NOT_SUPPORTED	Amounts greater than 100 million are not supported.

Base URL: http://smartsafe.dyndns.tv:8091

Autenticando Requisições

Para autenticar requisições, inclua um cabeçalho Authorization com o valor "Bearer {ACCESS_TOKEN}".

Obtenha o token de acesso através do endpoint POST /oauth/token

Todos os endpoints que precisam de autenticação estão marcados com um selo requires authentication na documentação abaixo.

Endpoints

Enviar uma venda

requires authentication

Este endpoint tem o objetivo de enviar uma venda.

Example request:

curl --request POST \
    "http://localhost:8085/api/sale" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"type\": \"CREDIT\",
    \"amount\": \"19.99\",
    \"card_number\": \"4176660000000100\",
    \"card_security_code\": \"597\",
    \"card_expiration_date\": \"2027-12\",
    \"card_holder_name\": \"John Doe\",
    \"installments\": \"1\"
}"

const url = new URL(
    "http://localhost:8085/api/sale"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "type": "CREDIT",
    "amount": "19.99",
    "card_number": "4176660000000100",
    "card_security_code": "597",
    "card_expiration_date": "2027-12",
    "card_holder_name": "John Doe",
    "installments": "1"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'http://localhost:8085/api/sale';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'type' => 'CREDIT',
            'amount' => '19.99',
            'card_number' => '4176660000000100',
            'card_security_code' => '597',
            'card_expiration_date' => '2027-12',
            'card_holder_name' => 'John Doe',
            'installments' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'http://localhost:8085/api/sale'
payload = {
    "type": "CREDIT",
    "amount": "19.99",
    "card_number": "4176660000000100",
    "card_security_code": "597",
    "card_expiration_date": "2027-12",
    "card_holder_name": "John Doe",
    "installments": "1"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Success: Venda enviada):


{
    "id": "43c0add3-a710-4839-90bd-6ab6e96c175f",
    "status": "ACCEPTED",
    "type": "CREDIT",
    "amount": 19.99
}

Example response (400, Bad Request: Dado obrigatório não informado):


{
    "message": "O campo {fieldName} é obrigatório.",
    "errors": {
        "{fieldName}": [
            "O campo {fieldName} é obrigatório."
        ]
    }
}

Example response (401, Unauthenticated: access_token expirado/inválido):


{
    "message": "Unauthenticated."
}

Example response (422, Unprocessed Entity: Valor informado para campo está com formato inválido.):


{
    "message": "O campo installments não pode ser menor do que 1 e maior do que 12.",
    "errors": {
        "installments": [
            "O campo installments não pode ser menor do que 1 e maior do que 12."
        ]
    }
}

Example response (422, Unprocessed Entity: Transações em débito não podem ter mais de 01 parcela.):


{
    "message": "Para transações de débito, o installment deve ser 1.",
    "errors": {
        "installments": [
            "Para transações de débito, o installment deve ser 1."
        ]
    }
}

Example response (500, Internal Server Error: Erro ao processar a venda.):


{
    "message": "Não foi possível processar a venda."
}

Example response (500, Internal Server Error: Conforme tabela de erros):


{
    "message": "INVALID_CVV: Invalid CVV. CVV should be 3 digits."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/sale

Headers

Authorization

Example: Bearer {ACCESS_TOKEN}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

type string

Example: CREDIT

Must be one of:

DEBIT
CREDIT

amount string

Example: 19.99

card_number string

Example: 4176660000000100

card_security_code string

Example: 597

card_expiration_date string

A data de expiração do cartão precisa estar no formato yyyy-mm
Example: 2027-12

card_holder_name string

Example: John Doe

installments string

Número de parcelas [1..12]. Para débito, informe o valor 1
Example: 1

Token de Acesso

Utilizamos o framework OAuth 2.0 para autorização. Por padrão, sempre utilizamos o client_credentials como grant_type.

Obter token de acesso

Endpoint para obter o access_token, chave utilizada para autorização em todos os endpoints protegidos da API no cabeçalho Authorization do tipo Bearer. Um access_token tem uma duração padrão de 24h.

Example request:

curl --request POST \
    "http://localhost:8085/oauth/token" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"{CLIENT_ID}\",
    \"client_secret\": \"{CLIENT_SECRET}\"
}"

const url = new URL(
    "http://localhost:8085/oauth/token"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "grant_type": "client_credentials",
    "client_id": "{CLIENT_ID}",
    "client_secret": "{CLIENT_SECRET}"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'http://localhost:8085/oauth/token';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'grant_type' => 'client_credentials',
            'client_id' => '{CLIENT_ID}',
            'client_secret' => '{CLIENT_SECRET}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'http://localhost:8085//oauth/token'
payload = {
    "grant_type": "client_credentials",
    "client_id": "{CLIENT_ID}",
    "client_secret": "{CLIENT_SECRET}"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, access_token gerado):


{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO..."
}

Example response (400, Bad Request: grant_type inválido/não informado):


{
    "error": "unsupported_grant_type",
    "error_description": "The authorization grant type is not supported by the authorization server.",
    "hint": "Check that all required parameters have been provided",
    "message": "The authorization grant type is not supported by the authorization server."
}

Example response (400, Bad Request: client_id não informado):


{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
    "hint": "Check the `client_id` parameter",
    "message": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
}

Example response (400, Bad Request: client_id/client_secret não encontrado):


{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
    "hint": "Check the `client_id` parameter",
    "message": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
}

Example response (401, Unauthorized: client_id/client_secret não encontrado):


{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

token_type string

Tipo do token. Padrão: Bearer

expires_in integer

Segundos restantes para o token expirar

access_token string

Token de acesso