Billing V1
by RealWave

Billing V1

Este especificação de integração ajuda a implementar integrações com a API RESTful Billing v1 do RealWave.

Entrypoint

https://{slug}.{entrypoint}.gateway.zup.me/billing/v1
slug
string required

Nome da Organização (Slug)

entrypoint
string required

Identificação do Ambiente da API

Enumeration:
Desenvolvimento

https://{slug}.dev.gateway.zup.me/billing/v1

Staging

https://{slug}.staging.gateway.zup.me/billing/v1

Produção

https://{slug}.gateway.zup.me/billing/v1

Documentação
Métodos de Requisição HTTP

As solicitações devem ser feitas usando o protocolo HTTPS para que o tráfego seja criptografado. A interface responde a diferentes métodos dependendo da ação necessária.

Métodos HTTP disponíveis na API Billing v1:

Método Ação
GET Consultar Dados
POST Salvar/Criar Dados
PUT Atualizar Dados
DELETE Deletar/Inativar Dados
Códigos de Status HTTP
Status Descrição
200 OK Indica que a requisição foi realizada com sucesso
201 Created Indica que o recurso foi criado com sucesso
304 Not Modified The requested resource has not been modified.
400 Bad Request Requisição inválida enviada pelo client (consumidor da API)
401 Unauthorized Os dados de autorização de acesso a API são inválidos
403 Forbidden Credenciais de acesso sem autorização de acesso ao recurso REST
404 Not Found Erro indicando que o recurso REST não foi encontrado ou não está disponivel
Cross Origin Resource Sharing (CORS)

Para fazer solicitações para a API a partir de outros domínios, a API implementa o suporte a Compartilhamento de Recursos de Origem Cruzada (CORS).

Suporte CORS geralmente é usado para criar solicitações AJAX fora do domínio de que o pedido foi originado. Isso é necessário para implementar projetos como painéis de controle que utilizam a API. Isso informa o navegador que ele pode enviar solicitações para um domínio externo.

O procedimento que o navegador inicia para executar essas ações (exceto solicitações GET) começa enviando uma solicitação “pré-vôo”. Isso define o Header Origin e usa o metodo OPTIONS. O servidor irá responder de volta com os métodos que permite e alguns dos limites que impõe. O cliente então envia a solicitação real se ele estiver dentro das restrições permitidas.

Esse processo geralmente é feito em segundo plano pelo navegador, mas você pode usar curl para emular esse processo usando o exemplo fornecido. Os cabeçalhos que serão definidos para mostrar as restrições são:

  • Access-Control-Allow-Origin : Este é o domínio que é enviado pelo cliente ou navegador como origem do pedido. É definido através de um Header Origin.

  • Access-Control-Allow-Methods : Especifica as opções permitidas para solicitações desse domínio. Isso geralmente será todos os métodos disponíveis.

  • Access-Control-Expose-Headers : Isso conterá os cabeçalhos que estarão disponíveis para pedidos do domínio de origem.

  • Access-Control-Max-Age : Este é o período de tempo que o acesso é considerado válido. Após a expiração, um novo pré-vôo deve ser enviado.

  • Access-Control-Allow-Credentials : Isso será definido como true. Ele basicamente permite que você envie seu token OAuth para autenticação.

Você não precisa se preocupar com os detalhes desses cabeçalhos, porque o navegador normalmente fará todo o trabalho para você.

Introdução

Bem vindo a documentação da API Billing v1 do RealWave. Todo acesso as APIs é realizado através de conexões HTTPS criptografadas. A versão 1.0 da API é acessada através do subpath v1/. As funcionalidades do BIlling são disponibilizadas através de APIs, possibilitando a integração com outras soluções Esta documentação de API irá fornecer uma introdução geral do design e da tecnologia sobre a qual ela foi desenvolvida, além disso fornecerá informações de referência sobre endpoints especificos desta API.

Métodos da API
CREDIT-CARDS

Recurso que representa cartão de crédito no RealWave

Cadastrar cartão de crédito
POST /credit-cards
Detalhar cartão de crédito
GET /credit-cards/{id}
Listar cartões de crédito
GET /credit-cards
Inativar Cartão de Crédito
DELETE /credit-cards/{id}
Definir Cartão de crédito Principal
PUT /credit-card/{id}
Cadastrar cartão de crédito
POST /credit-cards

Notes

Cadastra um novo cartão de crédito para um determinado cliente do RealWave.

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Request body

Object
creditCard
Object
number
string

Número do cartão

Example:
4464787364928764
brand
string

Bandeira do cartão

Example:
VISA
expirationMonth
string

Mês de vencimento

Example:
12
expirationYear
string

Ano de vencimento

Example:
2019
holder
string

Nome do titular

Example:
JOHN DOO
cvv
string

Código de segurança

Example:
782
main
boolean nullable

Definir como cartão principal

Example:
true
Examples

Payload de request

{
  "creditCard": {
    "number": "4464787364928764",
    "brand": "VISA",
    "expirationMonth": "12",
    "expirationYear": "2019",
    "holder": "JOHN DOO",
    "cvv": "782",
    "main": true
  }
}

Responses

201 Created

Sucesso

Body
Object
creditCard
Object
id
integer
Example:
6912
brand
string
Example:
VISA
lastDigits
string
Example:
8764
expirationMonth
string
Example:
12
expirationYear
string
Example:
2019
holder
string
Example:
JOHN DOO
customerId
string
Example:
fadc5428-5f79-4932-aa75-216f614a073a
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
Examples

Payload de response com sucesso

{
  "creditCard": {
    "id": 6912,
    "brand": "VISA",
    "lastDigits": "8764",
    "expirationMonth": "12",
    "expirationYear": "2019",
    "holder": "JOHN DOO",
    "customerId": "fadc5428-5f79-4932-aa75-216f614a073a",
    "main": true,
    "active": true,
    "locked": false
  }
}
400 Bad request

Payload inválido

Body
Object
errors
Array
Object
code
string
Example:
CHA-114
message
string
Example:
The date of credit card is invalid.
Examples

Payload de response com erro de negócio

{
    "errors": [
        {
            "code": "CHA-114",
            "message": "The date of credit card is invalid."
        }
    ]
}
401 Falha de autenticação
500 Erro interno
Detalhar cartão de crédito
GET /credit-cards/{id}

Detalha um cartão de crédito de um cliente no RealWave.

Path variables

id
string required

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
integer
Example:
2226
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
12
expirationYear
string
Example:
2019
holder
string
Example:
JOHN DOO
customerId
string
Example:
73072bfbfadc5428-5f79-4932-aa75-216f614a073a
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
reasonBlock
Object
createdAt
string
Example:
2017-01-19T17:55:56.957152
updatedAt
string
Example:
2017-04-10T14:58:03.966096
Examples

Payload de response com sucesso

{
    "id": 2226,
    "brand": "VISA",
    "bin": "446478",
    "lastDigits": "8764",
    "expirationMonth": "12",
    "expirationYear": "2019",
    "holder": "JOHN DOO",
    "customerId": "73072bfbfadc5428-5f79-4932-aa75-216f614a073a",
    "main": true,
    "active": true,
    "locked": false,
    "reasonBlock": {},
    "createdAt": "2017-01-19T17:55:56.957152",
    "updatedAt": "2017-04-10T14:58:03.966096"
}
204 No Content

Nenhum cartão para exibir

401 Falha de autenticação
500 Erro interno
Listar cartões de crédito
GET /credit-cards

Lista os cartões de crédito de um determinado cliente

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
integer
Example:
2226
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
12
expirationYear
string
Example:
2019
holder
string
Example:
JOHN DOO
customerId
string
Example:
73072bfbfadc5428-5f79-4932-aa75-216f614a073a
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
reasonBlock
Object
createdAt
string
Example:
2017-01-19T17:55:56.957152
updatedAt
string
Example:
2017-04-10T14:58:03.966096
Examples

Payload de response com sucesso

[{
    "id": 2226,
    "brand": "VISA",
    "bin": "446478",
    "lastDigits": "8764",
    "expirationMonth": "12",
    "expirationYear": "2019",
    "holder": "JOHN DOO",
    "customerId": "73072bfbfadc5428-5f79-4932-aa75-216f614a073a",
    "main": true,
    "active": true,
    "locked": true,
    "reasonBlock": {},
    "createdAt": "2017-01-19T17:55:56.957152",
    "updatedAt": "2017-04-10T14:58:03.966096"
}]
204 No Content

Nenhum cartão para exibir

401 Falha de autenticação
500 Erro interno
Inativar Cartão de Crédito
DELETE /credit-cards/{id}

Inativa um cartão de crédito no Billing do RealWave.

Path variables

id
string required

Identificador único do cartão de crédito

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK
Body
Object
id
integer
Example:
2452
brand
string
Example:
VISA
bin
string
Example:
***
lastDigits
string
Example:
9827
expirationMonth
string
Example:
***
expirationYear
string
Example:
***
holder
string
Example:
João c c resende
customerId
string
Example:
1c94d23d-150a-4d2c-ad97-c1d31dca4a25
main
boolean
active
boolean
locked
boolean
reasonBlock
Object
createdAt
string
Example:
2017-01-22T10:20:33.701585
updatedAt
string
Example:
2017-03-06T01:50:44.004707
Examples
{
    "id": 2452,
    "brand": "VISA",
    "bin": "***",
    "lastDigits": "9827",
    "expirationMonth": "***",
    "expirationYear": "***",
    "holder": "João c c resende",
    "customerId": "1c94d23d-150a-4d2c-ad97-c1d31dca4a25",
    "main": true,
    "active": true,
    "locked": true,
    "reasonBlock": {},
    "createdAt": "2017-01-22T10:20:33.701585",
    "updatedAt": "2017-03-06T01:50:44.004707"
}
Definir Cartão de crédito Principal
PUT /credit-card/{id}

Define o cartão de crédito principal de um cliente no Billing do RealWave.

Path variables

id
string required

Identificador único do cartão de crédito

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Request body

Object
main
boolean
Example:
true
Examples
{
    "main": true
}

Responses

200 OK
Body
Object
id
integer
Example:
3287
brand
string
Example:
VISA
bin
string
Example:
498442
lastDigits
string
Example:
5941
expirationMonth
string
Example:
***
expirationYear
string
Example:
***
holder
string
Example:
Margareth C R Silva
customerId
string
Example:
59b1d523-a392-4513-a248-9bc435a5fa82
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
reasonBlock
Object
createdAt
string
Example:
2017-02-03T12:23:23.703664
updatedAt
string
Example:
2017-04-05T14:20:41.893124
Examples
{
    "id": 3287,
    "brand": "VISA",
    "bin": "498442",
    "lastDigits": "5941",
    "expirationMonth": "***",
    "expirationYear": "***",
    "holder": "Margareth C R Silva",
    "customerId": "59b1d523-a392-4513-a248-9bc435a5fa82",
    "main": true,
    "active": true,
    "locked": true,
    "reasonBlock": {},
    "createdAt": "2017-02-03T12:23:23.703664",
    "updatedAt": "2017-04-05T14:20:41.893124"
}
SUBSCRIPTIONS

Recurso que representa uma assinatura de recorrência no RealWave

Criar assinatura para um cliente
POST /subscriptions
Listar assinaturas de um cliente
GET /subscriptions
Consultar detalhes de uma assinatura
GET /subscriptions/{id}
Cancelar Assinatura
DELETE /subscriptions/{id}
Criar assinatura para um cliente
POST /subscriptions

Criação de assinaturas com pagamento recorrente

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Request body

Object
name
string

Nome/descrição da assinatura

Example:
Assinatura mensal revista quatro rodas
paymentMethod
string

Meio de pagamento a ser utilizado na recorrência

Example:
CREDIT_CARD
amount
Object

Valor da recorrência

total
string

Valor monetário

Example:
12.90
currency
string

Moeda

Example:
BRL
billingCycle
Object

Ciclo de faturamento

Example: 
{
    "recurringPeriod": "MONTH",
    "recurringCycles": 1
}
recurringPeriod
string

Período da recorrência (DAY: a cada X dias, MONTH: a cada X meses, YEAR: a cada X anos)

Example:
MONTH
recurringCycles
integer

Ciclo da recorrência (valor do X na configuração acima)

Example:
1
startDate
string date nullable

Data de início da recorrência (se omitido, calcula-se a partir de hoje + ciclo configurado. Se informado a primeira recorrência é cobrada naquela data, e as demais a partir da data informada + ciclo configurado)

Example:
2017-04-12
recurringEndDate
string date nullable

Data para o fim da recorrência (se omitido, será cobrado até que a assinatura cancelada)

donation
boolean

Se a assinatura é uma doação (pode ser utilizado para fins fiscais)

products
Array

Lista de itens da assinatura

Object
externalId
string nullable

Código do item para uso do segmento

Example:
REV-4RODAS-1
name
string

Nome do item

Example:
Exemplar revista quatro rodas
price
string

Preço do item

Example:
12.90
quantity
integer

Quantidade do item

Example:
1
sku
string nullable

Código identificador único do item

uri
string nullable

URI do item

customFields
Object nullable

Campo customizável pelo segmento

Example: 
{"customField": "customValue"}
externalId
string nullable

Código externo para uso do segmento

Examples

Payload de request

{
    "name": "Assinatura mensal revista quatro rodas",
    "paymentMethod": "CREDIT_CARD",
    "amount": {
        "total": "12.90",
        "currency": "BRL"
    },
    "billingCycle": {
        "recurringPeriod": "MONTH",
        "recurringCycles": 1,
        "startDate": "2017-04-12"
    },
    "donation": true,
    "products": [
        {
            "externalId": "REV-4RODAS-1",
            "name": "Exemplar revista quatro rodas",
            "price": "12.90",
            "quantity": 1
        }
    ],
    "customFields": {}
}

Responses

201 Created
Body
Object
id
integer
Example:
1
externalId
unknown nullable
name
string
Example:
Assinatura mensal revista quatro rodas
paymentMethod
string
Example:
DEBIT_REFILL
sellerAccount
Object
id
integer
Example:
1
organizationId
string
Example:
getnet
applicationId
string
Example:
da39a3ee5e6b4b0d3255bfef95601890afd80709
name
string
Example:
Nextel Digital
active
boolean
Example:
true
createdAt
string
Example:
2016-11-19T22:30:54.619415
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
12.90
currency
string
Example:
BRL
billingCycle
Object
startDate
string
Example:
2017-05-12
recurringPeriod
string
Example:
MONTH
recurringCycles
integer
Example:
1
recurringEndDate
unknown nullable
customFields
unknown nullable
donation
boolean
active
boolean
Example:
true
productItems
Array
Object
id
integer
Example:
1
externalId
string
Example:
REV-4RODAS-1
name
string
Example:
Exemplar revista quatro rodas
price
number
Example:
12.9
quantity
integer
Example:
1
sku
unknown nullable
uri
unknown nullable
customFields
unknown nullable
createdAt
string
Example:
2017-04-12T14:47:32.574993
Examples

Payload de response com sucesso

{
    "id": 1,
    "externalId": null,
    "name": "Assinatura mensal revista quatro rodas",
    "paymentMethod": "DEBIT_REFILL",
    "sellerAccount": {
        "id": 1,
        "organizationId": "getnet",
        "applicationId": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "name": "Nextel Digital",
        "active": true,
        "createdAt": "2016-11-19T22:30:54.619415"
    },
    "customerId": "b87e3f87-e21b-4c38-bvcd-872da17f765f",
    "amount": {
        "total": "12.90",
        "currency": "BRL"
    },
    "billingCycle": {
        "startDate": "2017-05-12",
        "recurringPeriod": "MONTH",
        "recurringCycles": 1,
        "recurringEndDate": null
    },
    "customFields": null,
    "donation": true,
    "active": true,
    "productItems": [
        {
            "id": 1,
            "externalId": "REV-4RODAS-1",
            "name": "Exemplar revista quatro rodas",
            "price": 12.9,
            "quantity": 1,
            "sku": null,
            "uri": null,
            "customFields": null,
            "createdAt": "2017-04-12T14:47:32.574993"
        }
    ]
}
422 Unprocessable entity

Erro de negócio

Body
Object
errors
Array
Object
code
string
Example:
CHA-156
message
string
Example:
Credit card main not found..
Examples

Payload de response com erro de negócio

{
    "errors": [
        {
            "code": "CHA-156",
            "message": "Credit card main not found.."
        }
    ]
}
401 Falha de autenticação
400 Bad request

Payload inválido

Body
Object
code
string
Example:
CHA-171
message
string
Example:
Invalid end date. It must be equal to or greater than startDate.
Examples

Payload de response com erro de validação

{
    "code": "CHA-171",
    "message": "Invalid end date. It must be equal to or greater than startDate."
}
500 Erro interno
Listar assinaturas de um cliente
GET /subscriptions

Lista assinaturas de um determinado cliente

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
integer
Example:
1
externalId
unknown nullable
name
string
Example:
Assinatura mensal revista quatro rodas
paymentMethod
string
Example:
DEBIT_REFILL
sellerAccount
Object
id
integer
Example:
1
organizationId
string
Example:
getnet
applicationId
string
Example:
da39a3ee5e6b4b0d3255bfef95601890afd80709
name
string
Example:
Nextel Digital
active
boolean
Example:
true
createdAt
string
Example:
2016-11-19T22:30:54.619415
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
12.90
currency
string
Example:
BRL
billingCycle
Object
startDate
string
Example:
2017-05-12
recurringPeriod
string
Example:
MONTH
recurringCycles
integer
Example:
1
recurringEndDate
unknown nullable
customFields
unknown nullable
donation
boolean
Example:
true
active
boolean
Example:
true
productItems
Array
Object
id
integer
Example:
1
externalId
string
Example:
REV-4RODAS-1
name
string
Example:
Exemplar revista quatro rodas
price
number
Example:
12.9
quantity
integer
Example:
1
sku
unknown nullable
uri
unknown nullable
customFields
unknown nullable
createdAt
string
Example:
2017-04-12T14:47:32.574993
204 No Content

Nenhuma assinatura para exibir

401 Falha de autenticação
500 Erro interno
Consultar detalhes de uma assinatura
GET /subscriptions/{id}

Detalha uma assinatura de um determinado cliente

Path variables

id
string required

ID da assinatura

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
integer
Example:
1
externalId
unknown nullable
name
string
Example:
Assinatura mensal revista quatro rodas
paymentMethod
string
Example:
DEBIT_REFILL
sellerAccount
Object
id
integer
Example:
1
organizationId
string
Example:
getnet
applicationId
string
Example:
da39a3ee5e6b4b0d3255bfef95601890afd80709
name
string
Example:
Nextel Digital
active
boolean
Example:
true
createdAt
string
Example:
2016-11-19T22:30:54.619415
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
12.90
currency
string
Example:
BRL
billingCycle
Object
startDate
string
Example:
2017-05-12
recurringPeriod
string
Example:
MONTH
recurringCycles
integer
Example:
1
recurringEndDate
unknown nullable
customFields
unknown nullable
donation
boolean
Example:
true
active
boolean
Example:
true
productItems
Array
Object
id
integer
Example:
1
externalId
string
Example:
REV-4RODAS-1
name
string
Example:
Exemplar revista quatro rodas
price
number
Example:
12.9
quantity
integer
Example:
1
sku
unknown nullable
uri
unknown nullable
customFields
unknown nullable
createdAt
string
Example:
2017-04-12T14:47:32.574993
204 No Content

Nenhuma assinatura para exibir

401 Falha de autenticação
500 Erro interno
Cancelar Assinatura
DELETE /subscriptions/{id}

Cancela uma determinada assinatura no Billing do RealWave.

Path variables

id
string required

Identificador único da Assinatura

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK
Body
Object
id
integer
Example:
29508
externalId
unknown nullable
name
string
Example:
PLANO BASICO
paymentMethod
string
Example:
CREDIT_CARD
sellerAccount
Object
id
integer
Example:
1
organizationId
string
Example:
***
applicationId
string
Example:
***
name
string
Example:
Nextel Digital
active
boolean
Example:
true
createdAt
string
Example:
2016-11-19T22:30:54.619415
customerId
string
Example:
954448b4-4408-4312-82ac-e5bbdd181500
amount
Object
total
string
Example:
7.99
currency
string
Example:
BRL
billingCycle
Object
startDate
string
Example:
2017-04-07
recurringPeriod
string
Example:
DAY
recurringCycles
integer
Example:
7
recurringEndDate
unknown nullable
customFields
unknown nullable
donation
boolean
active
boolean
createdAt
string
Example:
2017-04-05T23:21:50.821986
updatedAt
string
Example:
2017-04-05T23:30:58.035
productItems
Array
Object
id
integer
Example:
73792
externalId
string
Example:
2ffa44a9-d977-4297-b0a8-d76ce5257db0
name
string
Example:
Aplicativo de Mensagens Semanal 7 Dias
price
integer
quantity
integer
Example:
1
sku
unknown nullable
uri
unknown nullable
customFields
unknown nullable
createdAt
string
Example:
2017-04-05T23:21:50.821986
Examples
{
    "id": 29508,
    "externalId": null,
    "name": "PLANO BASICO",
    "paymentMethod": "CREDIT_CARD",
    "sellerAccount": {
        "id": 1,
        "organizationId": "***",
        "applicationId": "***",
        "name": "Nextel Digital",
        "active": true,
        "createdAt": "2016-11-19T22:30:54.619415"
    },
    "customerId": "954448b4-4408-4312-82ac-e5bbdd181500",
    "amount": {
        "total": "7.99",
        "currency": "BRL"
    },
    "billingCycle": {
        "startDate": "2017-04-07",
        "recurringPeriod": "DAY",
        "recurringCycles": 7,
        "recurringEndDate": null
    },
    "customFields": null,
    "donation": true,
    "active": true,
    "createdAt": "2017-04-05T23:21:50.821986",
    "updatedAt": "2017-04-05T23:30:58.035",
    "productItems": [
        {
            "id": 73792,
            "externalId": "2ffa44a9-d977-4297-b0a8-d76ce5257db0",
            "name": "Aplicativo de Mensagens Semanal 7 Dias",
            "price": 1,
            "quantity": 1,
            "sku": null,
            "uri": null,
            "customFields": null,
            "createdAt": "2017-04-05T23:21:50.821986"
        }
    ]
}
PAYMENTS

Recurso que representa uma operação de pagamento no RealWave

Realizar pagamento
POST /payments
Estornar pagamento
POST /payments/{id}/reversals
Realizar pagamento
POST /payments

Realiza um pagamento de compra avulsa (não recorrente)

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Request body

Object
payment
Object
method
string

Meio de pagamento

Example:
CREDIT_CARD
data
Object
creditCard
Object
number
string

Número do cartão

Example:
4464787364928764
brand
string

Bandeira do cartão

Example:
VISA
expirationMonth
string

Mês de vencimento

Example:
12
expirationYear
string

Ano de vencimento

Example:
2019
holder
string

Nome do titular

Example:
JOHN DOO
cvv
string

Código de segurança

Example:
782
transaction
Object
amount
Object

Valor da compra

total
string

Valor monetário

Example:
4.90
currency
string

Moeda

Example:
BRL
items
Array
Object
code
string

Código do item

Example:
89882
description
string

Descrição do item

Example:
Exemplar revista quatro rodas do mês de Abril
price
string

Preço do item

Example:
4.90
quantity
integer

Quantidade do item

Example:
1
customFields
Object

Campo customizável pelo segmento

Example: 
{"customField": "customValue"}
discount
Object nullable

Desconto a ser aplicado no total da compra

Example: 
{
    "total": "1.00",
    "currency": "BRL"
}
total
string

Valor monetário

Example:
1.00
currency
string

Moeda

Example:
BRL
Examples

Payload de request

{
    "payment": {
        "method": "CREDIT_CARD",
        "data": {
            "creditCard": {
                "number": "4464787364928764",
                "brand": "VISA",
                "expirationMonth": "12",
                "expirationYear": "2019",
                "holder": "JOHN DOO",
                "cvv": "782"
            }
        }
    },
    "transaction": {
        "amount": {
            "total": "4.90",
            "currency": "BRL"
        },
        "items": [
            {
                "code": "89882",
                "description": "Exemplar revista quatro rodas do mês de Abril",
                "price": "4.90",
                "quantity": 1
            }
        ]
    },
    "customFields": {},
    "discount": {
        "total": "1.00",
        "currency": "BRL"
    }
}

Responses

201 Created

Sucesso

Body
Object
id
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:15.488979
recurrence
boolean
payment
Object
method
string
Example:
CREDIT_CARD
provider
string
Example:
Cielo
creditCard
Object
id
integer
Example:
1
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
08
expirationYear
string
Example:
2018
holder
string
Example:
JOHN DOO
customerId
string
Example:
c6e7fbce-8713-404d-b15a-31e36ee2995b
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
reasonBlock
Object
createdAt
string
Example:
2017-04-12T18:19:08.02712
updatedAt
string
Example:
2017-04-12T18:19:13.977937
items
Array
Object
id
integer
Example:
34977
code
string
Example:
89882
description
string
Example:
Exemplar revista quatro rodas do mês de Abril
quantity
integer
Example:
1
price
string
Example:
4.90
histories
Array
Object
id
integer
Example:
99413
chargerTransactionId
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
status
string
Example:
CONFIRMING
reversalReason
Object
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:21.584426
Examples
{
    "id": "8c216d10-9c61-426b-9784-11788a5323b0",
    "customerId": "b87e3f87-e21b-4c38-bvcd-872da17f765f",
    "amount": {
        "total": "4.90",
        "currency": "BRL"
    },
    "discount": {
        "total": "0.00",
        "currency": "BRL"
    },
    "createdAt": "2017-04-12T18:19:15.488979",
    "recurrence": true,
    "payment": {
        "method": "CREDIT_CARD",
        "provider": "Cielo",
        "creditCard": {
            "id": 1,
            "brand": "VISA",
            "bin": "446478",
            "lastDigits": "8764",
            "expirationMonth": "08",
            "expirationYear": "2018",
            "holder": "JOHN DOO",
            "customerId": "c6e7fbce-8713-404d-b15a-31e36ee2995b",
            "main": true,
            "active": true,
            "locked": true,
            "reasonBlock": {},
            "createdAt": "2017-04-12T18:19:08.02712",
            "updatedAt": "2017-04-12T18:19:13.977937"
        }
    },
    "items": [
        {
            "id": 34977,
            "code": "89882",
            "description": "Exemplar revista quatro rodas do mês de Abril",
            "quantity": 1,
            "price": "4.90"
        }
    ],
    "histories": [
        {
            "id": 99413,
            "chargerTransactionId": "8c216d10-9c61-426b-9784-11788a5323b0",
            "status": "CONFIRMING",
            "reversalReason": {},
            "amount": {
                "total": "4.90",
                "currency": "BRL"
            },
            "discount": {
                "total": "0.00",
                "currency": "BRL"
            },
            "createdAt": "2017-04-12T18:19:21.584426"
        }
    ]
}
400 Bad request

Requisição inválida

Body
Object
errors
Array
Object
code
string
Example:
CHA-122
message
string
Example:
Credit card not found.
422 Unprocessable Entity

Erro de negócio

Body
Object
transaction
Object
id
string
Example:
32b7ac59-6357-481c-b5fb-f9298eae65a2
createdAt
string
Example:
2017-04-13T06:54:46.148
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
items
Array
Object
code
string
Example:
803fa798-e235-4ff2-95ec-2a635fbab7ef
description
string
Example:
Exemplar revista quatro rodas do mês de Abril
quantity
integer
Example:
1
price
string
Example:
4.90
status
string
Example:
FAILED
recurrence
boolean
errors
Array
Object
code
string
Example:
XYZ
message
string
Example:
Payment denied
401 Falha de autenticação
500 Erro interno
Estornar pagamento
POST /payments/{id}/reversals

Estorna um pagamento já realizado.

Path variables

id
string required

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Request body

Object
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
reason
Object
code
string
Example:
009
description
string
Example:
Cliente desistiu da compra em até 7 dias

Responses

202 Accepted

Sucesso

Body
Object
id
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:15.488979
recurrence
boolean
Example:
true
payment
Object
method
string
Example:
CREDIT_CARD
provider
string
Example:
Cielo
creditCard
Object
id
integer
Example:
1
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
08
expirationYear
string
Example:
2018
holder
string
Example:
JOHN DOO
customerId
string
Example:
c6e7fbce-8713-404d-b15a-31e36ee2995b
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
Example:
true
reasonBlock
Object
createdAt
string
Example:
2017-04-12T18:19:08.02712
updatedAt
string
Example:
2017-04-12T18:19:13.977937
items
Array
Object
id
integer
Example:
34977
code
string
Example:
89882
description
string
Example:
Exemplar revista quatro rodas do mês de Abril
quantity
integer
Example:
1
price
string
Example:
4.90
histories
Array
Object
id
integer
Example:
99413
chargerTransactionId
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
status
string
Example:
CONFIRMING
reversalReason
Object
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:21.584426
Examples
{
  "id": "8c216d10-9c61-426b-9784-11788a5323b0",
  "customerId": "b87e3f87-e21b-4c38-bvcd-872da17f765f",
  "amount": {
    "total": "4.90",
    "currency": "BRL"
  },
  "discount": {
    "total": "0.00",
    "currency": "BRL"
  },
  "createdAt": "2017-04-12T18:19:15.488979",
  "recurrence": true,
  "payment": {
    "method": "CREDIT_CARD",
    "provider": "Cielo",
    "creditCard": {
      "id": 1,
      "brand": "VISA",
      "bin": "446478",
      "lastDigits": "8764",
      "expirationMonth": "08",
      "expirationYear": "2018",
      "holder": "JOHN DOO",
      "customerId": "c6e7fbce-8713-404d-b15a-31e36ee2995b",
      "main": true,
      "active": true,
      "locked": true,
      "reasonBlock": {},
      "createdAt": "2017-04-12T18:19:08.02712",
      "updatedAt": "2017-04-12T18:19:13.977937"
    }
  },
  "items": [
    {
      "id": 34977,
      "code": "89882",
      "description": "Exemplar revista quatro rodas do mês de Abril",
      "quantity": 1,
      "price": "4.90"
    }
  ],
  "histories": [
    {
      "id": 99413,
      "chargerTransactionId": "8c216d10-9c61-426b-9784-11788a5323b0",
      "status": "CONFIRMING",
      "reversalReason": {},
      "amount": {
        "total": "4.90",
        "currency": "BRL"
      },
      "discount": {
        "total": "0.00",
        "currency": "BRL"
      },
      "createdAt": "2017-04-12T18:19:21.584426"
    },
     {
      "id": 9941,
      "chargerTransactionId": "8c216d10-9c61-426b-9784-11788a5323b0",
      "status": "CONFIRMED",
      "reversalReason": {},
      "amount": {
        "total": "4.90",
        "currency": "BRL"
      },
      "discount": {
        "total": "0.00",
        "currency": "BRL"
      },
      "createdAt": "2017-04-12T18:19:21.584426"
    },
    {
      "id": 679888,
      "chargerTransactionId": "427aafe6-2368-4049-818f-8273627ed28a",
      "status": "REVERSING",
      "reversalReason": {
        "code": "-",
        "description": "Cliente desistiu da compra em até 7 dias."
      },
      "amount": {
        "total": "4.90",
        "currency": "BRL"
      },
      "discount": {
        "total": "0.00",
        "currency": "BRL"
      },
      "createdAt": "2017-04-12T15:31:57.09264"
    },
    {
      "id": 679889,
      "chargerTransactionId": "427aafe6-2368-4049-818f-8273627ed28a",
      "status": "REVERSED",
      "response": "",
      "reversalReason": {
        "code": "009",
        "description": "Cliente desistiu da compra em até 7 dias"
      },
      "amount": {
        "total": "4.90",
        "currency": "BRL"
      },
      "discount": {
        "total": "0.00",
        "currency": "BRL"
      },
      "createdAt": "2017-04-12T15:31:58.461279"
    }
  ]
}
422 Unprocessable Entity

Erro de negócio

Body
Object
errors
Array
Object
code
string
Example:
CHA-151
message
string
Example:
Amount higher than allowed. Transaction total: 4.90, already reversed: 4.90, available to reverse: 0.00
Examples

Payload de response com erro de negócio

{
    "errors": [
        {
            "code": "CHA-151",
            "message": "Amount higher than allowed. Transaction total: 4.90, already reversed: 4.90, available to reverse: 0.00"
        }
    ]
}
401 Falha de autenticação
400 Bad request

Requisição inválida

Body
Object
errors
Array
Object
code
string
Example:
CHA-120
message
string
Example:
Transaction not found.
500 Erro interno
TRANSACTIONS

Recurso que representa uma transação de pagamento feita no RealWave

Detalhar transação
GET /transactions/{id}
Listar transações
GET /transactions
Detalhar transação
GET /transactions/{id}

Detalha uma transação de pagamento avulso ou recorrente

Path variables

id
string required

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:15.488979
recurrence
boolean
Example:
true
payment
Object
method
string
Example:
CREDIT_CARD
provider
string
Example:
Cielo
creditCard
Object
id
integer
Example:
1
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
08
expirationYear
string
Example:
2018
holder
string
Example:
JOHN DOO
customerId
string
Example:
c6e7fbce-8713-404d-b15a-31e36ee2995b
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
Example:
true
reasonBlock
Object
createdAt
string
Example:
2017-04-12T18:19:08.02712
updatedAt
string
Example:
2017-04-12T18:19:13.977937
items
Array
Object
id
integer
Example:
34977
code
string
Example:
89882
description
string
Example:
Exemplar revista quatro rodas do mês de Abril
quantity
integer
Example:
1
price
string
Example:
4.90
histories
Array
Object
id
integer
Example:
99413
chargerTransactionId
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
status
string
Example:
CONFIRMING
reversalReason
Object
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:21.584426
Examples

Payload de response

{
    "id": "8c216d10-9c61-426b-9784-11788a5323b0",
    "customerId": "b87e3f87-e21b-4c38-bvcd-872da17f765f",
    "amount": {
        "total": "4.90",
        "currency": "BRL"
    },
    "discount": {
        "total": "0.00",
        "currency": "BRL"
    },
    "createdAt": "2017-04-12T18:19:15.488979",
    "recurrence": true,
    "payment": {
        "method": "CREDIT_CARD",
        "provider": "Cielo",
        "creditCard": {
            "id": 1,
            "brand": "VISA",
            "bin": "446478",
            "lastDigits": "8764",
            "expirationMonth": "08",
            "expirationYear": "2018",
            "holder": "JOHN DOO",
            "customerId": "c6e7fbce-8713-404d-b15a-31e36ee2995b",
            "main": true,
            "active": true,
            "locked": true,
            "reasonBlock": {},
            "createdAt": "2017-04-12T18:19:08.02712",
            "updatedAt": "2017-04-12T18:19:13.977937"
        }
    },
    "items": [
        {
            "id": 34977,
            "code": "89882",
            "description": "Exemplar revista quatro rodas do mês de Abril",
            "quantity": 1,
            "price": "4.90"
        }
    ],
    "histories": [
        {
            "id": 99413,
            "chargerTransactionId": "8c216d10-9c61-426b-9784-11788a5323b0",
            "status": "CONFIRMING",
            "reversalReason": {},
            "amount": {
                "total": "4.90",
                "currency": "BRL"
            },
            "discount": {
                "total": "0.00",
                "currency": "BRL"
            },
            "createdAt": "2017-04-12T18:19:21.584426"
        }
    ]
}
204 No Content

Nenhuma transação para exibir

401 Falha de autenticação
500 Erro interno
Listar transações
GET /transactions

Lista transações de pagamento avulso ou recorrente

Request parameters

gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c
startDate
string date required

Data inicial do período

Example:
2016-01-01
endDate
string date required

Data final do período

Example:
2016-12-31
paymentMethod
string optional

Meio de pagamento (CREDIT_CARD, DEBIT_CARD, BILLET)

Example:
CREDIT_CARD
paymentMethodId
integer optional

Identificador do meio de pagamento

Example:
1
statusIn
string optional

Status da transação. Pode ser um ou mais status

Example:
statusIn=CONFIRMED,REVERSED

Request headers

X-Customer-Id
string required

ID do Cliente no RealWave

X-Tracking-Id
string optional

ID de rastreabilidade. Gerado pela app consumidora.

Example:
TEST:1a-2b-3c-4d
X-Application-Id
string required

Id de Aplicação Interno do RealWave

Example:
65290a37b07dbea3f15a340bc47cb978ea1044e8

Responses

200 OK

Sucesso

Body
Object
id
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
customerId
string
Example:
b87e3f87-e21b-4c38-bvcd-872da17f765f
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:15.488979
recurrence
boolean
Example:
true
payment
Object
method
string
Example:
CREDIT_CARD
provider
string
Example:
Cielo
creditCard
Object
id
integer
Example:
1
brand
string
Example:
VISA
bin
string
Example:
446478
lastDigits
string
Example:
8764
expirationMonth
string
Example:
08
expirationYear
string
Example:
2018
holder
string
Example:
JOHN DOO
customerId
string
Example:
c6e7fbce-8713-404d-b15a-31e36ee2995b
main
boolean
Example:
true
active
boolean
Example:
true
locked
boolean
Example:
true
reasonBlock
Object
createdAt
string
Example:
2017-04-12T18:19:08.02712
updatedAt
string
Example:
2017-04-12T18:19:13.977937
items
Array
Object
id
integer
Example:
34977
code
string
Example:
89882
description
string
Example:
Exemplar revista quatro rodas do mês de Abril
quantity
integer
Example:
1
price
string
Example:
4.90
histories
Array
Object
id
integer
Example:
99413
chargerTransactionId
string
Example:
8c216d10-9c61-426b-9784-11788a5323b0
status
string
Example:
CONFIRMING
reversalReason
Object
amount
Object
total
string
Example:
4.90
currency
string
Example:
BRL
discount
Object
total
string
Example:
0.00
currency
string
Example:
BRL
createdAt
string
Example:
2017-04-12T18:19:21.584426
204 No Content

Nenhuma transação para exibir

401 Falha de autenticação
500 Erro interno
Glossário
X-Application-Key
string required

Chave de autenticação da API

Example:
cac419a0059e0135bd5a021e75abe44c
Content-type
string required

Identificador de tipo de mídia suportada pela API.

Default:
application/json
gw-app-key
string required

Chave de autenticação da API

Example:
ec2fdb00172a0135bde6021e75abe44c
Operations: Cadastrar cartão de crédito Cancelar Assinatura Consultar detalhes de uma assinatura Criar assinatura para um cliente Definir Cartão de crédito Principal Detalhar cartão de crédito Detalhar transação Estornar pagamento Inativar Cartão de Crédito Listar assinaturas de um cliente Listar cartões de crédito Listar transações Realizar pagamento