Direct integration

API Direct Payment

Request Base URL

  Test Environment : https://gateway-test.pagsmile.com
  Prod Environment : https://gateway.pagsmile.com

EndPoints

  /trade/pay

Request Header

Parameter	Required	Description
Content-Type	recommend	application/json
Authorization	yes	Basic Base64(app_id:security_key)

Request Body (JSON format)

Parameter	Type	Required	Max Length(or Default Value)	Description
app_id	string	yes	32	created app's id at dashboard
timestamp	string	yes	19	yyyy-MM-dd HH:mm:ss
out_trade_no	string	yes	64	ID given by the merchant in their system
method	string	no	32	Payment Methods
channel	string	no	32	sub channel(only use at method 'Wallet')
order_currency	string	yes	3	BRL for brazil
order_amount	decimal	yes	0.01 ~ 99999999999999.99	request payment amount
subject	string	yes	128	payment reason or item title
content	string	Yes	255	payment reason detail or item detail. . This will be shown on the bank bill.
notify_url	string	yes		IPN URL to merchant(start with http
buyer_id	string	yes		merchant user's id
timeout_express	string	no	90m	m(minutes), h(hours), d(days), c(always end in currency day)
token	string	no		required for CreditCard
fingerprint	string	no		required for CreditCard
issuer	string	no		issuer of credit card（required for CreditCard）
installments	integer	no	1	installments for CreditCard
bank	string	no		bank code, required for DepositExpress (itau,santander,bradesco,banco-do-brasil,caixa) Cash (Use bank_id from Bank Query); BankTransfer (Use bank_id from Bank Query); Khipu (Use bank_id from Bank Query);
language_code	string	no		language code, required for Cash, BankTransfer. (Use language_code from Bank query)
customer.name	string	yes		user's name
customer.email	string	yes		user's email
customer.phone	string	yes		user's mobile phone number
customer.identify.number	string	yes		user's ID number
customer.identify.type	string	yes		user's ID type
address.zip_code	string	yes		zip code
address.state	string	yes		state
address.city	string	yes		city
address.street_number	string	yes		street1 number
address.street	string	yes		street1
address.neighborhood	string	no		street2
user_ip	string	no		user's IP address(required for CreditCard)
website_url	string	no	128	merchant website URL

Request Sample

curl --location --request POST 'https://gateway.pagsmile.com/trade/pay' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "app_id",
    "content": "content",
    "method": "Boleto",
    "notify_url": "notify_url",
    "order_amount": 10,
    "order_currency": "BRL",
    "out_trade_no": "{{$randomUUID}}",
    "subject": "subject",
    "timeout_express": "1h",
    "timestamp": "{{datetime}}",
    "customer": {
      "name": "name",
      "email": "email",
	  "phone": "phone",
	  "identify": {
		"number":"number",
		"type":"type“，
	  }
      ...
    },
    "address": {
      "zip_code": "84043450",
      "state": "Parana",
      "city": "Ponta Grossa",
      "street"; "Colônia Dona Luíza",
      "street_number": "18",
    },
    "user_ip": "127.0.0.1"
}'

Http Response (JSON format)

Parameter	Type	Description	Method
code	string	return code
msg	string	return msg
sub_code	string	return sub code(only error)
sub_msg	string	return sub msg(only error)
out_trade_no	string	request out_trade_no
trade_no	string	Pagsmile trade NO.
trade_status	string
pay_url	string	Redirect users to the payment URL	Argentina: Khipu, Bank Transfer; Brazil: PIX, Lottery, Boleto, DepositExpress; Mexico: SPEI, OXXO, OXXOPay; Colombia: PSE, Efecty, Bancolombia, SuRed, Wallet ClaroPay, Gana; Chile: Khipu, Pago46, Bank Transfer, Cash, Wallet Chek; Peru: Bank Transfer, Cash; Ecuador: Bank Transfer, Cash; Costa Rica: Cash, BNCR; Panama, Guatemala: Cash; Bolivia, Paraguay, Uruguay: Bank Transfer;
reference	string	The value of reference is the ticket number that the user needs to use for payment	Argentina: Bank Transfer, Rapipago, PagoFacil; Mexico: SPEI, CoDi, Cash; Colombia: Bancolombia, SuRed, Gana; Chile: Cash; Peru: Bank Transfer, Cash; Costa Rica: Cash, BNCR; Panama, Guatemala: Cash; Bolivia, Paraguay, Uruguay: Bank Transfer
barcode	string	Use the value of barcode to generate a scanable barcode can help users to make payment faster	Argentina: Rapipago, PagoFacil; Brazil: Lottery, Boleto; Mexico: OXXO, OXXOPay
qr_code	string	QR code	Brazil: PIX; Mexico: CoDi
qr_code_url	string	System generated images of qr code which can be used directly on merchant website depending on needs.	Brazil: PIX
qr_code_img	string	System generated images of qr code which can be used directly on merchant website depending on needs.	Brazil: PIX
provider_owner	string	bank info : account owner; only in DepositExpress
provider_owner_document	string	bank info : account owner document; only in DepositExpress
provider_agency	string	bank info : account agency; only in DepositExpress
provider_number	string	bank info : account number; only in DepositExpress
partner_code	string	The value of reference is the ticket number that the user needs to use for payment	Colombia: Bancolombia, SuRed, Gana; Costa Rica: BNCR
bank_name	string	bank info : bank name	Brazil: DepositExpress; Mexico: SPEI
bank_no	string	Users only need to use the value of bank_no to finish payment at loterica store	Brazil: Lottery
bank_code	string	The ticket number that the user needs to use for payment	Brazil: Boleto
clabe	string	Unique automatically generated bank account	Only SPEI Mexico
wallet_url	string	Redirect users to the wallet payment page	Only in Wallet payment method Brazil: AME, PicPay; Colombia: Wallets (Tpaga, Dale, Daviplata, Movii, Nequi, Rappipay)
app_link_url	string	Redirect users to the wallet app payment page (for mobile walle application)	For mobile wallet app use only Brazil: AME; Chile: Mach, Vita
instruction	string	Take the recipient's bank details from the response parameter - "instruction" and present to users	Bolivia, Paraguay, Uruguay: Bank Transfer

Return Code (Success)

{
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "{out_trade_no}",
    "trade_no": "{trade_no}",
    "trade_status": "PROCESSING",
    "pay_url": "https://checkout-testv2.pagsmile.com/checkout?prepay_id=XX",
    "barcode": "{barcode}",
    "qr_code": "{qr_code}",
    "provider_owner": "{provider_owner}",
    "provider_owner_document": "{provider_owner_document}",
    "provider_agency": "{provider_agency}",
    "provider_number": "{provider_number}",
    "wallet_url": "{wallet_url}",
    "app_link_url": "{app_link_url}"
}

Return Code (Fail)

{
    "code": "40002",
    "msg": "Business Failed",
    "sub_code": "invalid-signature",
    "sub_msg": "invalid signature"
}

Attention

Return_url is not required in the request parameters, you can also append the return_url after the web_url when redirect:

http://checkout.pagsmile.com?prepay_id={$prepay_id}

↓↓↓

http://checkout.pagsmile.com?prepay_id={$prepay_id}&return_url={$return_url}