Hosted Checkout
In this guide, you will learn how to integrate the Hosted Checkout into your app to accept payments from your customers. The Hosted Checkout is a secure and easy way to accept payments from your customers without having to handle sensitive card information.
Integration Steps
- Before implementing a Hosted Session solution, check with Your payment service provider to ensure you meet the following prerequisites: Ensure that you have a merchant account and that your merchant profile is enabled for the Hosted Session service. Ensure that you use API v18 or later. Select and set up your API authentication method.
Session Basics
Making a Payment
Interpret the Transaction Response
Subsequent Operations
Testing the Integration
Consuming webhooks
When your app receives a webhook request from Prahsys, check the type
attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc.
Example webhook payload
{
"id": "a056V7R7NmNRjl70",
"type": "conversation.updated",
"payload": {
"id": "WAz8eIbvDR60rouK"
// ...
}
}
In the example above, a conversation was updated
, and the payload type is a conversation
.
Event types
- Name
contact.created
- Description
A new contact was created.
- Name
contact.updated
- Description
An existing contact was updated.
- Name
contact.deleted
- Description
A contact was successfully deleted.
- Name
conversation.created
- Description
A new conversation was created.
- Name
conversation.updated
- Description
An existing conversation was updated.
- Name
conversation.deleted
- Description
A conversation was successfully deleted.
- Name
message.created
- Description
A new message was created.
- Name
message.updated
- Description
An existing message was updated.
- Name
message.deleted
- Description
A message was successfully deleted.
- Name
group.created
- Description
A new group was created.
- Name
group.updated
- Description
An existing group was updated.
- Name
group.deleted
- Description
A group was successfully deleted.
- Name
attachment.created
- Description
A new attachment was created.
- Name
attachment.updated
- Description
An existing attachment was updated.
- Name
attachment.deleted
- Description
An attachment was successfully deleted.
Example payload
{
"id": "a056V7R7NmNRjl70",
"type": "message.updated",
"payload": {
"id": "SIuAFUNKdSYHZF2w",
"conversation_id": "xgQQXg3hrtjh7AvZ",
"contact": {
"id": "WAz8eIbvDR60rouK",
"username": "KevinMcCallister",
"phone_number": "1-800-759-3000",
"avatar_url": "https://assets.protocol.chat/avatars/kevin.jpg",
"last_active_at": 705103200,
"created_at": 692233200
},
"message": "I’m traveling with my dad. He’s at a meeting. I hate meetings.",
"reactions": [],
"attachments": [],
"read_at": 705103200,
"created_at": 692233200,
"updated_at": 692233200
}
}
Security
To know for sure that a webhook was, in fact, sent by Prahsys instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-protocol-signature
, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:
Verifying a request
const signature = req.headers['x-protocol-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')
if (hash === signature) {
// Request is verified
} else {
// Request could not be verified
}
If your generated signature matches the x-protocol-signature
header, you can be sure that the request was truly coming from Prahsys. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Protocol. Don't commit your secret webhook key to GitHub!