PaymentsCreate Payment

Create Payment

POST/v1/paymenthttps://api.securitypag.com

Authentication: Bearer · API key

To create a payment, use the route v1/payment. This route supports credit card, bank slip and PIX payments.

Address format: Address fields are automatically rendered based on the value provided in country.

If country = BR, the Brazilian format will be displayed with the following fields: state, city, district, street, number, complement e zipCode.

For other countries, the international format will be automatically displayed with the following fields: state, city, line1, line2 e zipCode.

Tip: just provide the correct country — the fields will adjust automatically.

Request body

Sent as JSON.

amountintegerrequired
Total payment amount in cents. Example: R$ 1,00.
currencystringrequired
Payment currency (e.g. BRL, USD, EUR).
methodstringrequired
Payment method (PIX, BOLETO, CREDIT_CARD).
descriptionstringrequired
Payment description.
externalRefstring
External payment reference.
notificationUrlstring
URL where payment webhooks will be sent.
ipstring
Customer IP address.
payerobjectrequired4 fields
Payer information.
- namestringrequired
  Full name of the payer.
- taxIdstringrequired
  Payer document.
- emailstring
  Payer email address.
- phonestring
  Payer phone number. May be required by some processors.
itemsarray of objectsrequired4 fields
List of products included in the payment.
- quantityintegerrequired
  Product quantity. Must be greater than zero.
- namestringrequired
  Product name.
- priceintegerrequired
  Unit price in cents. Example: 100 = R$1.00.
- typestringrequired
  Product type [DIGITAL, PHYSICAL].
deliveryobject2 fields
Entrega do pedido, obrigatório caso o produto seja do tipo PHYSICAL
- feeintegerrequired
  Taxa de entrega do pedido em centavos (este valor não é adicionado ao amount). Exemplo: R$ 1,00.
- addressobjectrequired8 fields
  Delivery address. The address format depends on the country provided. If country = BR use the Brazilian format (district, street, number). For other countries use the international format (line1, line2).
  - countrystringrequired
    Country code following ISO 3166-1 alpha-2 standard (e.g., BR, US).
  - statestringrequired
    State or province (e.g., SP, CA, NY). Used when country = BR.
  - citystringrequired
    City. Required when country = BR.
  - districtstringrequired
    District or neighborhood. Required when country = BR.
  - streetstringrequired
    Street name. Required when country = BR.
  - numberstringrequired
    Address number. Required when country = BR.
  - complementstring
    Address complement (apartment, building, unit, etc).
  - zipCodestringrequired
    ZIP code or postal code.
splitsarray of strings
List of split IDs. Example: ["split_id_1", "split_id_2"].
cardobject3 fields
Credit card data when method is CREDIT_CARD.
- tokenstringrequired
  Card token.
- installmentsintegerrequired
  Number of installments (1 to 12).
- billingAddressobject8 fields
  Billing address.
  - countrystringrequired
    Country code following ISO 3166-1 alpha-2 standard (e.g., BR, US).
  - statestringrequired
    State or province (e.g., SP, CA, NY). Used when country = BR.
  - citystringrequired
    City. Required when country = BR.
  - districtstringrequired
    District or neighborhood. Required when country = BR.
  - streetstringrequired
    Street name. Required when country = BR.
  - numberstringrequired
    Address number. Required when country = BR.
  - complementstring
    Address complement (apartment, building, unit, etc).
  - zipCodestringrequired
    ZIP code or postal code.
boletoobject1 fields
Required data when payment method is BOLETO.
- billingAddressobject8 fields
  The address format depends on the country provided. If country = BR use the Brazilian format (district, street, number). For other countries use the international format (line1, line2).
  - countrystringrequired
    Country code following ISO 3166-1 alpha-2 standard (e.g., BR, US).
  - statestringrequired
    State or province (e.g., SP, CA, NY). Used when country = BR.
  - citystringrequired
    City. Required when country = BR.
  - districtstringrequired
    District or neighborhood. Required when country = BR.
  - streetstringrequired
    Street name. Required when country = BR.
  - numberstringrequired
    Address number. Required when country = BR.
  - complementstring
    Address complement (apartment, building, unit, etc).
  - zipCodestringrequired
    ZIP code or postal code.
metadataobject9 fields
Payment metadata used for tracking and auditing.
- providerstringrequired
  Source responsible for creating the payment.
- orderIdstringrequired
  Unique order identifier.
- sellerTaxIdstringrequired
  Seller tax document.
- sellerEmailstringrequired
  Seller email address.
- checkoutUrlstring
  Checkout URL.
- returnUrlstring
  Return URL after payment.
- shopUrlstring
  Sales or offer page.
- referrerLinkstring
  Immediate referrer URL.
- extrastring
  Free field for additional metadata.
utmsobject7 fields
UTM parameters identifying the traffic source of the payment.
- utmSourcestring
  Traffic source that originated the access, such as google, facebook or newsletter.
- utmMediumstring
  Campaign medium or channel, such as cpc, email or social.
- utmCampaignstring
  Campaign name responsible for the access, such as black-friday-2026.
- utmContentstring
  Ad variation or creative that originated the access.
- utmTermstring
  Keyword associated with the ad or search that originated the access.
- srcstring
  Traffic origin code, forwarded in the URL as src. Identifies where the click came from.
- sckstring
  Secondary tracking code, forwarded in the URL as sck. Segments the origin within the campaign.

Responses

200Response object returned when the payment is successfully created or retrieved.

idstring
Unique payment identifier in the system.
amountintegerdefault: 0
Total payment amount in cents.
methodstring
Payment method used (PIX, CREDIT_CARD, BOLETO).
currencystring
Currency code used in the payment (e.g. BRL).
statusstring
Current payment status (e.g. PENDING, PROCESSING, PAID, REFUSED, REFUNDED, MED, CHARGEDBACK).
descriptionstring
Payment description.
installmentsintegerdefault: 1
Number of installments.
payerobject4 fields
Payer information.
- namestring
  Full name of the payer.
- taxIdstring
  Payer document number.
- emailstring
  Payer email address.
- phonestring
  Payer phone number including area code.
externalRefstring
External payment reference defined by the integrator.
orderIdstring
Order identifier in the integrator system.
notificationUrlstring
URL configured to receive notifications (webhooks).
paidAtstring
Date and time when the payment was completed.
refundedAtstring
Refund date and time, when applicable.
createdAtstring
Payment creation date and time.
updatedAtstring
Last payment update date and time.
dataobject8 fields
Payment method–specific data.
- methodstring
  Payment method related to the returned data.
- copypastestring
  PIX copy-and-paste code (when method is PIX).
- messagestring
  Card processor response message.
- cardHolderstring
  Name printed on the card.
- cardNumberstring
  Masked card number.
- cardExpMonthstring
  Card expiration month.
- cardExpYearstring
  Card expiration year.
- barcodestring
  Boleto barcode.
splitsarray of objects5 fields
Payment split configuration.
- amountintegerdefault: 0
  Amount allocated to the split receiver in cents.
- currencystring
  Split currency.
- percentinteger
  Split percentage (e.g. 100 = 100%).
- storeIdstring
  Store or receiver identifier.
- splitIdstring
  Split identifier, when applicable.
itemsarray of objects4 fields
List of products included in the payment.
- quantityinteger
  Product quantity. Must be greater than zero.
- namestring
  Product name.
- priceinteger
  Unit price in cents. Example: 100 = R$1.00.
- typestring
  Product type [DIGITAL, PHYSICAL].
metadataobject9 fields
Payment metadata used for tracking and control.
- providerstring
  Source responsible for creating the payment.
- orderIdstring
  Unique order identifier.
- sellerTaxIdstring
  Seller tax document.
- sellerEmailstring
  Seller email address.
- checkoutUrlstring
  Checkout URL where the payment was initiated.
- returnUrlstring
  User redirection URL after payment flow.
- shopUrlstring
  Sales or offer page that originated the purchase.
- referrerLinkstring
  Immediate referrer URL before accessing the offer.
- extrastring
  Free field for additional metadata.
utmsobject7 fields
UTM parameters identifying the traffic source of the payment.
- utmSourcestring
  Traffic source that originated the access.
- utmMediumstring
  Campaign medium or channel.
- utmCampaignstring
  Campaign name responsible for the access.
- utmContentstring
  Ad variation or creative that originated the access.
- utmTermstring
  Keyword associated with the ad or search that originated the access.
- srcstring
  Traffic origin code (src parameter) forwarded in the URL.
- sckstring
  Secondary tracking code (sck parameter) forwarded in the URL.

400Response object returned when the request contains invalid data.

Something wrong on this page? Talk to us