Pagamentos PIX

Nesta seção serão descritas e mantidas todas as APIs de interação com o produto de pagamentos/recebimentos de banking para o PIX que são expostas para nossos clientes finais.

A rota da API para sandbox é: https://apigw-sandbox.zoop.ws/v2

Não se deve usar o 2FA em sandbox.

post
Criar pagamento Pix por Chave

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments
Request
Response
Request
Path Parameters
marketplace_id
required
string
ID do Marketplace
holder_id
required
string
ID do Holder
account_id
required
string
ID da Conta
Headers
X-Auth-Token-Reading
required
string
Token de leitura do 2FA
X-Session-Token
required
string
Token de sessão do 2FA
Body Parameters
transaction_id
optional
string
Campo exclusivo para transações com QR Code. Identificação externa da transação PIX. É um campo opcional preenchido com o número criado e informado pelo QR Code dinâmico. É usado para que o PSP recebedor possa conciliar o pagamento recebido com o QR Code gerado. Máximo de 35 caracteres.
amount
required
number
Valor do pagamento
description
optional
string
Descrição do pagamento. Não é permitido caracteres especiais
creditor
required
object
Objeto que representa o recebedor do pagamento
national_registration
optional
string
Representa o CPF/CNPJ do recebedor do Pix - Parâmetro pertencente ao objeto creditor
psp
optional
number
Código da instituição participante do Pix onde a conta do recebedor está criada - Parâmetro pertencente ao objeto creditor
key
required
object
Objeto que representa a chave de endereçamento que contem a conta alvo do recebimento do Pix
type
required
string
Representa o tipo de chave de endereçamento. Domínio: phone, email, evp e national_registration. Parâmetro pertencente ao objeto key
value
required
string
Representa o valor da chave de endereçamento. Phone +99999999999999, email [email protected], evp xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx e national_registration xxxxxxxxxxx e xxxxxxxxxxxxxx - Parâmetro pertencente ao objeto key
Response
201: Created
A transação foi incluída com sucesso e está pronta para ser executada.
{
"id":"026b9c0e9fd34b32872906d5b64efbee",
"end_to_end_id":"E00038166201907261559y6j6mt9l0pi",
"transaction_id":"d747dc8fffec48a69830b40af4078fe1",
"marketplace_id":"0f8546897d6f41f4b3d81049693071ee",
"status":"pending",
"amount":120.50,
"description":"Churrasco fim pandemia",
"debtor":{
"national_registration":"15405039098",
"name":"José da Silva",
"type":"natural_person",
"holder_id":"ec1865e565a04bcab9994a395dd6393d",
"account":{
"psp":{
"code":"19468242",
"name":"Zoop Tecnologia e Meios de Pagamento S.A."
},
"digital_account_id":"0ce048eebf024b26957207c53430aabb",
"number":"45789",
"routing_number":"0001",
"type":"cacc"
}
},
"creditor":{
"national_registration":"84154427008",
"name":"Maria da Silva",
"type":"natural_person",
"account":{
"psp":{
"code":"60746948",
"name":"Bradesco S.A"
},
"number":"600000",
"routing_number":"3000",
"type":"cacc"
}
}
}
400: Bad Request
A requisição contém dados inválidos de alguma natureza
{
"status": "bad_request",
"type": "invalid_request",
"code": 2000,
"message": "Validation field error",
"category": "business",
"status_code": 400,
"fields": {
"account_id": {"code":1000,"message":"Account Id is required"},
"key.type": {"code":1001,"message":"Key type is required"}
}
}
404: Not Found
Indica que algum recurso não foi encontrado
{
"status": "not_found",
"type": "not_found",
"code": 3000,
"message": "Marketplace not found",
"category": "business",
"status_code": 404
}
412: Precondition Failed
Indica que algum pré-requisito de estado do sistema não foi atendido.
{
"status": "precondition_failed",
"type": "invalid_request",
"code": 4000,
"message": "Maximum entry count allowed reached",
"category": "business",
"status_code": 412
}
{
"transaction_id":"d747dc8fffec48a69830b40af4078fe1",
"amount":12050,
"description":"Churrasco fim pandemia",
"creditor":{
"national_registration":"84154427008",
"psp":"60746948",
"key":{
"value":"+552198744587",
"type":"phone"
}
}
}

post
Criar pagamento Pix por dados da conta

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do Holder
account_id
required
string
Id da conta
Headers
X-Auth-Token-Reading
required
string
Token de leitura do 2FA
X-Session-Token
required
string
Token de sessão do 2FA
Body Parameters
amount
required
number
Valor do pagamento
creditor
required
object
Objeto que representa o recebedor do pagamento
account
required
object
Objeto referente a conta alvo de recebimento do Pix - Objeto pertencente ao objeto creditor
number
required
number
Número da conta alvo de recebimento do Pix - Parâmetro pertencente ao objeto account
routing_number
required
number
Código da agência onde a conta foi criada - Parâmetro pertencente ao objeto account
type
required
string
Tipo de conta: cacc (conta corrente ou conta digital), slry (conta salário) e svgs (poupança) - Parâmetro pertencente ao objeto account
name
required
string
Representa o nome do recebedor - Parâmetro pertencente ao objeto creditor
national_registration
required
string
Representa o CPF/CNPJ do recebedor do Pix - Parâmetro pertencente ao objeto creditor
psp
required
number
Código da instituição participante do Pix onde a conta do recebedor está criada - Parâmetro pertencente ao objeto creditor
description
optional
string
Descrição do pagamento. Não é permitido caracteres especiais
transaction_id
optional
string
Campo exclusivo para transações com QR Code. Identificação externa da transação PIX. É um campo opcional preenchido com o número criado e informado pelo QR Code dinâmico. É usado para que o PSP recebedor possa conciliar o pagamento recebido com o QR Code gerado. Máximo de 35 caracteres.
Response
201: Created
{
"id":"026b9c0e9fd34b32872906d5b64efbee",
"end_to_end_id":"E00038166201907261559y6j6mt9l0pi",
"transaction_id":"d747dc8fffec48a69830b40af4078fe1",
"marketplace_id":"0f8546897d6f41f4b3d81049693071ee",
"status":"pending",
"amount":120.50,
"description":"Churrasco fim pandemia",
"debtor":{
"national_registration":"15405039098",
"name":"José da Silva",
"type":"natural_person",
"holder_id":"ec1865e565a04bcab9994a395dd6393d",
"account":{
"psp":{
"code":"19468242",
"name":"Zoop Tecnologia e Meios de Pagamento S.A."
},
"digital_account_id":"0ce048eebf024b26957207c53430aabb",
"number":"45789",
"routing_number":"0001",
"type":"cacc"
}
},
"creditor":{
"national_registration":"84154427008",
"name":"Maria da Silva",
"type":"natural_person",
"account":{
"psp":{
"code":"60746948",
"name":"Bradesco S.A"
},
"number":"600000",
"routing_number":"3000",
"type":"cacc"
}
}
}pertencente ao objeto creditor
400: Bad Request
A requisição contém dados inválidos de alguma natureza
{
"status": "bad_request",
"type": "invalid_request",
"code": 2000,
"message": "Validation field error",
"category": "business",
"status_code": 400,
"fields": {
"account_id": {"code":1000,"message":"Account Id is required"},
"key.type": {"code":1001,"message":"Key type is required"}
}
}
404: Not Found
Indica que algum recurso não foi encontrado
{
"status": "not_found",
"type": "not_found",
"code": 3000,
"message": "Marketplace not found",
"category": "business",
"status_code": 404
}
412: Precondition Failed
Indica que algum pré-requisito de estado do sistema não foi atendido
{
"status": "precondition_failed",
"type": "invalid_request",
"code": 4000,
"message": "Maximum entry count allowed reached",
"category": "business",
"status_code": 412
}
{
"amount": 120000,
"creditor": {
"account": {
"number": "600000",
"routing_number": "3000",
"type": "cacc"
},
"name": "1234545667",
"national_registration": "84154427008",
"psp": "60746948"
},
"description": "Descrição",
"transaction_id": "Descrição"
}

post
Confirmar pagamento PIX

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:payment_id/confirm
Request
Response
Request
Path Parameters
marketplace_id
required
string
Representa o id do marketplace sob o qual o holder que está confirmando o pagamento está cadastrado
holder_id
required
string
Representa o id do holder que está confirmando o pagamento.
account_id
required
string
Representa o id da conta digital pertencente ao holder alvo que será usada para fornecer os recursos financeiros para o pagamento.
payment_id
required
string
Id do pagamento que será confirmado
Headers
X-Auth-Token-Reading
required
string
Token de leitura do 2FA
X-Session-Token
required
string
Token de sessão do 2FA
Response
202: Accepted
Transação executada com sucesso. Aguardando liquidação financeira no BACEN.
{
"id":"026b9c0e9fd34b32872906d5b64efbee",
"end_to_end_id":"E00038166201907261559y6j6mt9l0pi",
"transaction_id":"d747dc8fffec48a69830b40af4078fe1",
"marketplace_id":"0f8546897d6f41f4b3d81049693071ee",
"status":"executed",
"amount":120.50,
"description":"Churrasco fim pandemia",
"debtor":{
"national_registration":"15405039098",
"name":"José da Silva",
"type":"natural_person",
"holder_id":"ec1865e565a04bcab9994a395dd6393d",
"account":{
"psp":{
"code":"19468242",
"name":"Zoop Tecnologia e Meios de Pagamento S.A."
},
"digital_account_id":"0ce048eebf024b26957207c53430aabb",
"number":"45789",
"routing_number":"0001",
"type":"cacc"
}
},
"creditor":{
"national_registration":"84154427008",
"name":"Maria da Silva",
"type":"natural_person",
"account":{
"psp":{
"code":"60746948",
"name":"Bradesco S.A"
},
"number":"600000",
"routing_number":"3000",
"type":"cacc"
}
}
}
400: Bad Request
A requisição contém dados inválidos de alguma natureza
{
"status": "bad_request",
"type": "invalid_request",
"code": 2000,
"message": "Validation field error",
"category": "business",
"status_code": 400,
"fields": {
"account_id": {"code":1000,"message":"Account Id is required"},
"key.type": {"code":1001,"message":"Key type is required"}
}
}
404: Not Found
Indica que algum recurso não foi encontrado
{
"status": "not_found",
"type": "not_found",
"code": 3000,
"message": "Marketplace not found",
"category": "business",
"status_code": 404
}
412: Precondition Failed
Indica que algum pré-requisito de estado do sistema não foi atendido.
{
"status": "precondition_failed",
"type": "invalid_request",
"code": 4000,
"message": "Maximum entry count allowed reached",
"category": "business",
"status_code": 412
}

post
Cancelar pagamento PIX

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:payment_id/cancel
Request
Response
Request
Path Parameters
marketplace_id
required
string
Representa o id do marketplace sob o qual o holder está cancelando o pagamento
holder_id
required
string
Representa o id do holder que está cancelando o pagamento
account_id
required
string
Representa o id da a conta digital do holder que está cancelando o pagamento
paymentId
required
string
Id do pagamento que será cancelado
Headers
X-Auth-Token-Reading
required
string
Token de leitura do 2FA
X-Session-Token
required
string
Token de sessão do 2FA
Response
200: OK

post
Devolver recebimento de PIX

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:transaction_id/refunds
Request
Response
Request
Path Parameters
marketplace_id
required
string
Representa o id do marketplace sob o qual está devolvendo o pagamento
holder_id
required
string
Representa o id do holder que está devolvendo o pagamento
account_id
required
string
Representa o id da conta digital que está devolvendo o pagamento
transactionId
required
string
Representa o id da transação PIX de crédito que sofrerá a devolução
Headers
X-Auth-Token-Reading
required
string
Token de leitura do 2FA
X-Session-Token
required
string
Token de sessão do 2FA
Body Parameters
amount
required
integer
Representa o valor a ser devolvido
reason
required
object
Informa a razão da devolução
additional_information
required
string
Descrição da razão
code
required
string
Código da devolução. Enum: AM05, AM09, BE08, DS28, FOCR, FR01, MD06, NARR, RUTA, SL11, SL12 e UPAY
Response
201: Created
{
"amount": 1800,
"created_at": "2021-01-07T15:41:52.532Z",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"original_transaction": {
"amount": 0,
"created_at": "2021-01-07T15:41:52.532Z",
"creditor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"debtor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"description": "Descrição",
"end_to_end_id": "E00038166201907261559y6j6mt9l0pi",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"message_id": "M1729809268c599330486f52c88b8f70",
"refunded_amount": 0,
"status": "pending",
"transaction_id": "d747dc8fffec48a69830b40af4078fe1"
},
"reason": {
"additional_information": "NARR",
"code": "NARR"
},
"return_id": "D1946824220201126121971204711114",
"status": "EXECUTED",
"updated_at": "2021-01-07T15:41:52.532Z"
}
{
"amount": 12000,
"reason": {
"additional_information": "envio errado",
"code": "AM05"
}
}

get
Consultar pagamento PIX

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:paymentId
Request
Response
Request
Path Parameters
marketplace_id
required
string
Representa o id do marketplace
holder_id
required
string
Representa o id do portador da conta digital
account_id
required
string
Representa o id da conta digital
payment_id
required
string
Representa o id do pagamento PIX
page
optional
integer
Indica a página a ser exibida
size
optional
integer
Indica a quantidade de registros a ser retornado por página
Headers
X-Auth-Token-Reading
required
string
Id de leitura do 2FA
X-Session-Token
required
string
Id de sessão do 2FA
Response
200: OK
{
"amount": 0,
"created_at": "2021-01-08T12:22:27.618Z",
"creditor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"debtor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"description": "Descrição",
"end_to_end_id": "E00038166201907261559y6j6mt9l0pi",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"message_id": "M1729809268c599330486f52c88b8f70",
"refunded_amount": 0,
"status": "pending",
"transaction_id": "d747dc8fffec48a69830b40af4078fe1"
}

get
Consultar devolução

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:transaction_id/refunds/:refund_id
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder que realizou a devolução
account_id
required
string
Id da conta que realizou a devolução
transaction_id
required
string
Id da transação que e sofreu a devolução
refund_id
required
string
Id da devolução
page
optional
integer
Indica a página a ser exibida
size
optional
integer
Indica a quantidade de registros a ser retornado por página
Headers
X-Auth-Token-Reading
required
string
Id de leitura do 2FA
X-Session-Token
required
string
Id de sessão do 2FA
Response
200: OK
{
"amount": 0,
"created_at": "2021-01-07T15:44:50.004Z",
"creditor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"debtor": {
"account": {
"digital_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"number": "string",
"psp": {
"code": "string",
"name": "string"
},
"routing_number": "string",
"type": "CACC"
},
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"national_registration": "string",
"type": "BUSINESS"
},
"description": "Descrição",
"end_to_end_id": "E00038166201907261559y6j6mt9l0pi",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"message_id": "M1729809268c599330486f52c88b8f70",
"refunded_amount": 0,
"status": "pending",
"transaction_id": "d747dc8fffec48a69830b40af4078fe1"
}

get
Listar devoluções

https://api.zoop.ws/v3/marketplaces/:marketplace_id/banking/pix/holders/:holder_id/accounts/:account_id/payments/:transaction_id/refunds
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta digital que realizou as devoluções
transactionId
required
string
Id da transação que sofreu devoluções
page
optional
string
Indica a página a ser exibida
size
optional
string
Indica a quantidade de registros a ser retornado por página
Response
200: OK