Documents

Payment Webhook

Suggest Edits

The payment webhook is sent when the status of the payment transaction changes.
Refer below for the sample payload.

{
  "currency": "USD",
  "amount": 500,
  "order_ref": "2mbbExY77pp8iC0AQ1ucWymnd3c",
  "channel_order_ref": "20240926HULUNYGP6MA2",
  "merchant_order_ref": "2mbbDi9wX3wAgLUDCnRMbQwkwZm_1",
  "country_code": "US",
  "status": "Success",
  "channel_key": "PAYLETTER",
  "method_name": "Payletter Credit Card",
  "method_key": "PAYLETTER_CREDIT_CARD",
  "method_sub_type": "INT_CREDIT_CARD",
  "buyer_name": "N K",
  "buyer_email": "[email protected]",
  "buyer_phone": "+919876543210",
  "buyer_address1": "address",
  "buyer_address2": "address_2",
  "buyer_city": "City",
  "buyer_country": "US",
  "signature_hash": "lSzZqm8I4G46b4nDtCqSUQ5/YgAhWn+IsFU893hciFM=",
  "status_code": "2000",
  "status_reason": "SUCCESS",
  "status_channel_reason": "SUCCESS | Transaction is success",
  "created_at": "2024-09-26 10:55:14.573735 +0000 UTC",
  "is_refund_allowed": true,
  "is_multi_refund_allowed": true,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
  "description": "Test payment",
  "ip_address": "103.23.238.249",
  "link_order_ref": "54A42644707B254",
  "payment_link_ref": "2mbbDODqt4ZojDHa14IaiYwM4AM",
  "source": "checkout",
  "payment_method_used": "테스트카드 | ************4242",
  "merchant_name": "ShopCity",
  "merchant_key": "qcFJvupbcbdcyNFg",
  "merchant_email_address": "[email protected]",
  "channel_name": "PAYLETTER",
  "environment": "sandbox",
  "user_message": "The transaction is successful.",
  "receipt_url": "https://test-merchant.payletter.com/Receipt/OpenReceipt?id=5061796d656e74323031352334215061796c6574746572504f518a125381e51a6fe576e2d9bb88e0f5d9930060ebb3043d158a0afe8d779574a6a13c0544\u0026pgcode=PL",
  "masked_card_number": "************4242",
  "cross_border_data": {},
  "additional_payment_details": {},
  "installment_details": {}
}

📘

Info

Refer to Payment Webhook Signature section to verify the signature_hash received in the webhook
During testing you can use FOSS Webhook server to setup a webhook endpoint. Create a sample webhook endpoint at webhook.site

Parameter list

amount
float64

The amount of the transaction

currency
string

The currency of the transaction

merchant_order_ref
string

Order Reference sent by merchant to initiate transaction

order_ref
string

PortOne's Order Reference, used further for refund and other disputes

channel_order_ref
string

Payment Channel's Order Reference

payment_link_ref
string

Payment Link's Order Reference

link_order_ref
string

Order Reference sent by merchant to initiate payment link

country_code
string

The country code of the transaction

user_message
string

The user message of the transaction

status
string

The current status of the transaction

status_channel_reason
string

The reason given by the PSP for the status

status_code
string

The status code of the transaction. Refer Error Codes List for more details.

status_reason
string

The reason for the transaction status

signature_hash
string

Calculate hash as mentioned at Hash Generation Reference, verify if it is equal to signature_hash received in the webhook

buyer_address1
string

The primary address of the buyer

buyer_address2
string

The secondary address of the buyer

buyer_city
string

The city of the buyer

buyer_country
string

The country code of the buyer

buyer_email
string

The email address of the buyer

buyer_name
string

The name of the buyer

channel_key
string

The key of the payment channel

channel_name
string

The name of the payment channel

method_key
string

The key of the payment method used for the transaction

method_name
string

The name of the payment method used for the transaction

method_sub_type
string

The sub type of the payment method used for the transaction

merchant_key
string

The PortOne key of the merchant

merchant_name
string

The name of the merchant

merchant_email_address
string

The email address of the merchant

source
string

The source of the transaction

ip_address
string

The IP address of the buyer

user_agent
string

The user agent of the transaction

created_at
string

The date and time when the transaction was created

is_refund_allowed
boolean

This boolean flag indicates whether a transaction is eligible for a refund, with a value of true meaning the refund can be processed and false meaning refunds are not permitted.

is_multi_refund_allowed
boolean

This boolean flag indicates whether multiple partial refunds can be issued for a single transaction. A value of true means that the transaction supports multiple refunds, while false means only a single refund or no partial refunds are allowed.

environment
string

The environment of the transaction

refund_status
string

The status of the refund

description
string

The description of the transaction

payment_method_used
string

The payment method used for the transaction

receipt_url
string

The URL of the receipt of the transaction

masked_card_number
string

The masked card number is the partially hidden representation of a credit or debit card number used for the transaction

cross_border_data
object

The cross border data of the transaction provided by the payment channel

additional_data
object

The additional data of the transaction provided by the payment channel

installment_details
object

The installment details of the transaction provided by the payment channel

Updated 13 days ago