This guide will help you send data to a third party without having the data touch your own servers.
PCI Vault will send the data to the third party with built-in exponential back-off, and will return the third party's response to you via webhook.
Sending data from PCI Vault is a 5-step process.
┌───────────┐ ┌─────────┐ ┌───────────┐
│Your Server│ │PCI Vault│ │Third Party│
└─────┬─────┘ └────┬────┘ └─────┬─────┘
│ │ │
│1) Create Webhook │ │
│ │ │
│2) Proxy Request │ │
│───────────────────────>│ │
│ │ │
│ │3) Send & Receive │
│ │<─────────────────>│
│ │ │
│4) Third Party Response │ │
│<───────────────────────│ │
│ │ │
│5) Webhook Response │ │
│───────────────────────>│ │
┌─────┴─────┐ ┌────┴────┐ ┌─────┴─────┐
│Your Server│ │PCI Vault│ │Third Party│
└───────────┘ └─────────┘ └───────────┘
Create a webhook endpoint on your server. The webhook endpoint must be accessible from the web and use HTTPS as its protocol.
To secure the webhook endpoint against bad actors, you must protect your webhook with a secret which can be submitted in an HTTP header. You will provide this secret to PCI Vault in step 2.
You can choose to
We recommend the first option and discourage the last option. All three options are allowed.
Make a POST request to /proxy/post. The body of the request must contain a request template in JSON.
For example:
{
"request": {
"method": "POST",
"url": "https://example-psp.com/process",
"headers": [
{"Content-Type": "application/json"},
{"Authorization": "Basic ZXhhbXBsZTpwYXNzd29yZA=="}
],
"body": "{\"mustache_template\": \"{{number}}\"}"
},
"webhook": {
"url": "https://reply-to.me",
"secret": "rIx9tXqTH10_ShEThqQZ2yRI0e9_aPP9"
}
}
May POST
{"mustache_template": "4111 1111 1111 1111"}
to
https://example-psp.com/process
with the specified headers included in the request.
The mustache template will be compiled with the data associated to the provided token.
For example:
{
"number": "{{number}}",
"cvv": {{cvv}},
"expiry": "02/25"
}
May generate a request body like
{
"number": "4111 1111 1111 1111",
"cvv": 234,
"expiry": "02/25"
}
PCI Vault will do the following validation before sending:
If PCI Vault responds with 200 OK, the request will be sent to the third party soon. Any other response code means that something went wrong and the request will not be sent.
PCI Vault will send the request to the third party on your behalf. If the third party responds with a 429 or 5xx error, PCI Vault will retry the request with exponential backoff until it succeeds or failed a number of times.
Any response by the third party that is not in the 5xx range, will be forwarded to you via webhook.
PCI Vault will send a POST
request to your webhook endpoint and include your secret
in the X-PCIVault-Webhook-Secret
header.
It is your responsibility to ensure the secret in the header matches to the one you sent.
The data in the POST
request will look like this:
{
"headers": [
{"Content-Type": "application/json"},
{"Content-Length": "24"},
{"X-Custom-Header": "custom-data"}
],
"body": "{\"status\": \"processed\"}",
"status": "200"
}
All headers in the third party's response is included and the response body is copied verbatim before being JSON escaped.
Please respond with an HTTP status code in 2xx range if you successfully processed
the request.
All other status codes will cause PCI Vault to retry the webhook with exponential backoff.
Every attempt at POST
ing to the webhook will be charged as a normal API Request.
Please handle the following cases accordingly:
404 Not Found
, or 401 Unauthorized
.
This probably means someone else is trying to send data on the webhook.403 Forbidden
.
In this case PCI Vault staff will be notified and contact you to resolve the issue.POST
request, please return 405 Method Not Allowed
.