Create Payment Link

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)

caution

The generated payment link will be valid only until the expirationDate provided in the request. After that date, the link will be automatically disabled and can no longer be used for payments.

Create a payment link

The Online Payments API also lets you create ready-to-use payment links with a predefined amount, providing a checkout page that can be used by the payer.

To create a payment link, send a POST request to /v1/paymentlink/new as shown below.

Webhook notifications

Automatic webhook

When a payment is made through a payment link, our platform can automatically send a notification to your application with the transaction data. This is an optional feature.

Learn more about Webhooks →

POST /v1/paymentlink/new

Via REST request with the following body:

Request

{ 
  "description": "<string>", 
  "value": "<double>", 
  "qttyInstallments": "<integer>", 
  "qttyInstallmentsCustom": ["<integer>"],
  "qttyInstallmentsIntFree": "<integer>", 
  "installmentsFee": "<double>",
  "expirationDate": "<dateTime>",
  "urlCallBack": "<string>"
} 

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	VALIDATION
description	Product/service description	String	Body	yes	Max 250 characters
value	Gross charge amount	decimal	Body	yes	Min 1.01 and max 999,999.99
qttyInstallments	Allowed number of installments. Required if qttyInstallmentsCustom is not provided	Int	Body	conditional
qttyInstallmentsCustom	Array of custom installment options. Required if qttyInstallments is not provided	Array[Int]	Body	conditional
qttyInstallmentsIntFree	Number of interest-free installments	Int	Body	yes	1 to 12
installmentsFee	Interest rate applied to installments greater than qttyInstallmentsIntFree (e.g., 1.5 = 1.5%)	double	Body	yes	0 to 100
expirationDate	Link expiration date	Date	Body	yes	Must be greater than today
urlCallBack	URL to receive webhook notifications when the payment is processed	String	Body	no	Max 500 characters

🟢 200

Payment link created successfully

{
  "id": "3c228652-122e-4da6-b572-4aea64caad63",
  "message": "Link de pagamento cadastrado com sucesso!",
  "description": "MENSALIDADE JOÃO DA SILVA SAURO",
  "value": 10.00,
  "expirationDate": "2025-08-29",
  "link": "https://faturas.sopague.com.br/link/3c228652-122e-4da6-b572-4aea64caad63"
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
id	Identifier of the created payment link.	string
message	Success message.	string
description	Product/service description for the created link.	string
value	Payment link amount.	decimal
expirationDate	Link expiration date.	string
link	Generated payment link URL.	string

🔴 400

Request error

[ 
    { 
      "tag": "", 
      "description": "Bandeira não identificada" 
    } 
] 

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

---

See also

Response codes

If a transaction fails, check the full response-code table to identify and properly handle errors:

Authorizer Host Response Codes →