Search Payment Links

API data

API Gateway
This API is used for payment gateway operations:

• Production: https://api.sopague.com.br/gateway
• Sandbox: https://api-hmg.sopague.com.br/gateway
• Architecture: Representational State Transfer (REST)

Payment link lookup

You can retrieve details of a payment link by its ID by calling the endpoint below:

GET /v1/paymentlink/information?id=<guid>

Via REST request.

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED
id	Identifier of the payment link to retrieve.	guid	query	yes

🟢 200

Success

{
  "id": "aed32670-c3e5-4192-8ab0-0e96f92e3408",
  "sellerDocumentNumber": "28249206000179",
  "sellerName": "SO PAGUE ",
  "description": "Teste",
  "value": 10.50,
  // Apenas um dos campos abaixo vai estar preenchido: qttyInstallments ou qttyInstallmentsCustom
  "qttyInstallments": 12,
  "qttyInstallmentsCustom": [3, 6, 9, 12],
  "qttyInstallmentsIntFree": 6,
  "installmentsFee": 1.5,
  "operationDate": "<datetime>",
  "expirationDate": "<datetime>",
  "link": ".../teste/aed32670-c3e5-4192-8ab0-0e96f92e3408",
  "message": "Olá! Estou enviando um link para você fazer o pagamento para NOME COBRADOR (01234567890123).\r\n\r\nDescrição: Teste\r\nValor: R$ 10,50\r\nVocê pode pagar em até 12x!\r\n\r\nLink: .../teste/aed32670-c3e5-4192-8ab0-0e96f92e3408\r\n\r\nInstruções: Basta clicar no link, preencher os dados solicitados, escolher a opção de pagamento que melhor atende suas necessidades e clicar em Pagar. Você pode pagar de onde quiser! :)",
  "status": 9,
  "statusFormat": "Desativado",
  "paymentDate": "<datetime>",
  "paymentValue": null,
  "paymentQttyInstallments": 6,
  "paymentAuthorizationCode": "149674",
  "paymentResultId": "020080286103040952150000006201850000000000",
  "history": [
    {
      "id": "05874f86-9167-4f02-8af5-4132d4541a4b",
      "idPaymentLink": "aed32670-c3e5-4192-8ab0-0e96f92e3408",
      "reason": null,
      "historyDate": "<datetime>",
      "status": 1,
      "statusFormat": "Em Aberto"
    },
    {
      "id": "d12192a0-1670-4d0a-a57d-5208d8d1652c",
      "idPaymentLink": "aed32670-c3e5-4192-8ab0-0e96f92e3408",
      "reason": null,
      "historyDate": "<datetime>",
      "status": 9,
      "statusFormat": "Desativado"
    }
  ]
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED
id	Payment link identifier	String	Body	yes
sellerDocumentNumber	Seller document number	String	Body	yes
sellerName	Seller name	String	Body	yes
description	Payment link description	String	Body	yes
value	Payment link amount	Int	Body	yes
qttyInstallments	Allowed installments. Present only when qttyInstallmentsCustom is not provided	Int	Body	conditional
qttyInstallmentsCustom	Array of custom installment options. Present only when qttyInstallments is not provided	Array[Int]	Body	conditional
qttyInstallmentsIntFree	Number of interest-free installments	Int	Body	yes
installmentsFee	Interest rate applied to installments greater than qttyInstallmentsIntFree (e.g., 1.5 = 1.5%)	double	Body	yes
operationDate	Operation date	Date	Body	yes
expirationDate	Link expiration date	Date	Body	yes
link	Payment link URL	String	Body	yes
message	Payment link message	String	Body	yes
status	Payment link status	Int	Body	yes
statusFormat	Status label	String	Body	yes
paymentDate	Date the link was paid	Date	Body	yes
paymentValue	Amount paid	Decimal	Body	yes
paymentQttyInstallments	Number of paid installments	Int	Body	yes
paymentAuthorizationCode	Payment authorization code	String	Body	yes
paymentResultId	Payment result ID (can be used as paymentId in search/cancel endpoints).	String	Body	no
history	Payment link status history	List	Body	yes

Payment link status values:

• 1 = Em Aberto
• 2 = Pago
• 3 = Expirado
• 9 = Desativado
• 99 = Falha

🔴 400

Request error

[ 
    { 
      "tag": "", 
      "description": "Nenhum link de pagamento cadastrado" 
    } 
] 

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
tag	Error tag	string
description	Error description	string

🔴 500

Internal error

[ 
    { 
        "tag": "", 
        "description": "Não foi possível executar comando. Erro desconhecido." 
    } 
]

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
tag	Error tag	string
description	Error description	string

Search payment link list

You can also search and retrieve a list of all payment links created by your account by calling the endpoint below:

GET /v1/paymentlink/list?initialPaymentDate={initialPaymentDate}&finalPaymentDate={finalPaymentDate}&status={status}&pageNumber={pageNumber}&pageSize={pageSize}&columnOrder={columnOrder}&sortDirection={sortDirection}

Data dictionary - Query parameters

PROPERTY	DESCRIPTION	TYPE	REQUIRED
initialPaymentDate	Payment date interval (start)	Date	yes
finalPaymentDate	Payment date interval (end)	Date	yes
status	Payment link status	Int	yes
pageNumber	Page number	Int	no
pageSize	Page size	Int	no
columnOrder	Sort column	String	no
sortDirection	Sort direction	String	no

🟢 200

Success

{
  "paginacao": {
    "numeroPagina": 1,
    "qtdeItensPagina": 1,
    "tamanhoPagina": 10,
    "totalPaginas": 1,
    "qtdeItensTotal": 1
  },
  "itens": [
    {
      "id": "aed32670-c3e5-4192-8ab0-0e96f92e3408",
      "description": "Teste",
      "value": 10.50,
      // Apenas um dos campos abaixo vai estar preenchido: qttyInstallments ou qttyInstallmentsCustom
      "qttyInstallments": 12,
      "qttyInstallmentsCustom": [3, 6, 9, 12], 
      "qttyInstallmentsIntFree": 6,
      "installmentsFee": 1.5,
      "status": 9,
      "statusFormat": "Desativado",
      "operationDate": "2024-09-02T11:55:58.7093323",
      "paymentDate": null,
      "payer": null,
      "paymentResultId": "020080286103040952150000006201850000000000"
    }
  ]
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED
paginacao.numeroPagina	Current page number	Int	Body	yes
paginacao.qtdeItensPagina	Number of items on the current page	Int	Body	yes
paginacao.tamanhoPagina	Page size	Int	Body	yes
paginacao.totalPaginas	Total pages	Int	Body	yes
paginacao.qtdeItensTotal	Total item count	Int	Body	yes
itens.id	Payment link identifier	String	Body	yes
itens.description	Payment link description	String	Body	yes
itens.value	Payment link amount	Decimal	Body	yes
itens.qttyInstallments	Allowed installments (present only when qttyInstallmentsCustom is not provided)	Int	Body	conditional
itens.qttyInstallmentsCustom	Array of custom installment options (present only when qttyInstallments is not provided)	Array[Int]	Body	conditional
itens.qttyInstallmentsIntFree	Number of interest-free installments	Int	Body	yes
itens.installmentsFee	Interest rate applied to installments greater than qttyInstallmentsIntFree (e.g., 1.5 = 1.5%)	double	Body	yes
itens.status	Payment link status	Int	Body	yes
itens.statusFormat	Status label	String	Body	yes
itens.operationDate	Operation date	DateTime	Body	yes
itens.paymentDate	Payment date	DateTime	Body	no
itens.payer	Payer	String	Body	no
itens.paymentResultId	Payment result ID (can be used as paymentId in search/cancel endpoints).	String	Body	no

🔴 400

Request error

[ 
    { 
      "tag": "", 
      "description": "Nenhum link de pagamento cadastrado" 
    } 
] 

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
tag	Error tag	string
description	Error description	string

🔴 500

Internal error

[ 
    { 
        "tag": "", 
        "description": "Não foi possível executar comando. Erro desconhecido." 
    } 
]

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
tag	Error tag	string
description	Error description	string