Criar recarga de celular

Este endpoint cria uma recarga de celular, reservando o valor do produto escolhido para o número informado. Veja a Visão Geral para os conceitos de produto e recarga.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

O parceiro esteja autenticado com um token válido.
O productId informado exista no catálogo de produtos de recarga.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/cellphone/recharge

--request POST 'https://sandbox.hiperbanco.com.br/cellphone/recharge' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "productId": "abc123",
  "areaCode": "71",
  "cellPhoneNumber": "999999999",
  "amount": 10,
  "affiliationKey": "chave-de-afiliacao",
  "metadata": {}
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
`version`	`cutting-edge`	Obrigatório. Essa propriedade garante que o response da API seja retornado no formato JSON.
`Authorization`	`Bearer token`	Obrigatório. Token de autorização do tipo Bearer. Requer o escopo `transactions:create`.
`Content-Type`	`application/json`	Obrigatório.

Parâmetros da rota (Path / Query)

Não é necessário enviar parâmetros na rota (path ou query) desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Campo	Tipo	Descrição	Especificação
`productId`	`string`	Obrigatório. Id do produto de recarga escolhido.	Entre 1 e 255 caracteres.
`areaCode`	`string`	Obrigatório. DDD do número de celular.	Deve ser um DDD brasileiro válido.
`cellPhoneNumber`	`string`	Obrigatório. Número de celular a ser recarregado, sem DDD.	Deve começar com 9. Exatamente 9 dígitos numéricos.
`amount`	`number`	Obrigatório. Valor da recarga, em reais.	Mínimo `1`, máximo `999999.99`.
`affiliationKey`	`string`	Opcional. Chave de afiliação do parceiro.	—
`metadata`	`object`	Opcional. Metadados adicionais da transação.	—

{
  "productId": "abc123",
  "areaCode": "71",
  "cellPhoneNumber": "999999999",
  "amount": 10,
  "affiliationKey": "chave-de-afiliacao",
  "metadata": {}
}

Resposta (Response)

O status code 201 indicará sucesso na requisição. Sendo bem-sucedido, o retorno irá trazer o seguinte campo em formato JSON:

Nome	Tipo	Descrição
`response`	`string`	Mensagem literal `reserved top-up amount`.
`id`	`string`	Id gerado para a recarga criada.

{
  "response": "reserved top-up amount",
  "id": "64a70040-8a3a-013d-d0e7-5686d902e59e"
}

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
`403`	`AccessDenied`	`You do not have permission to perform this action.`	O parceiro não tem permissão para criar recargas.
`412`	`PreconditionRequired`	`PIN has not been validated`	O PIN da conta ainda não foi validado antes desta chamada.
`400`	`InvalidInput`	`The request has invalid data.`	Os dados enviados no corpo da requisição são inválidos.
`404`	`AccountNotFound`	`Account not found`	A conta do parceiro não foi encontrada.
`404`	`ProductNotFound`	`ProductId incorrect.`	O `productId` informado não existe no catálogo de produtos.
`400`	`RechargeAmountExceededTheLimit`	`The amount value exceeds the maximum allowed limit`	O valor informado excede o limite máximo permitido para o produto.
`400`	`RechargeAmountIsBelowTheMinimum`	`The value is less than the minimum value allowed`	O valor informado é inferior ao mínimo permitido para o produto.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints, que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.