This guide will help you receive data from a third party without having the data touch your own servers.
PCI Vault will request and receive the data from the third party with built-in exponential back-off, and will return the resulting token to you via webhook.
Receiving data on PCI Vault is a 5-step process.
┌───────────┐ ┌─────────┐ ┌───────────┐
│Your Server│ │PCI Vault│ │Third Party│
└─────┬─────┘ └────┬────┘ └─────┬─────┘
│ │ │
│1) Create Webhook │ │
│ │ │
│2) Proxy Request │ │
│──────────────────────>│ │
│ │ │
│ │3) Send & Receive │
│ │<─────────────────>│
│ │ │
│4) Token │ │
│<──────────────────────│ │
│ │ │
│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/get. The body of the request must contain a request template in JSON.
For example:
{
"request": {
"method": "POST",
"url": "https://example-issuer.com/new-card",
"headers": [
{"Content-Type": "application/json"},
{"Authorization": "Basic ZXhhbXBsZTpwYXNzd29yZA=="}
],
"body": "This can be literally anything, it will be forwarded to the third party."
},
"webhook": {
"url": "https://reply-to.me",
"secret": "rIx9tXqTH10_ShEThqQZ2yRI0e9_aPP9"
}
}
This will POST
This can be literally anything, it will be forwarded to the third party.
to
https://example-issuer.com/new-card
with the specified headers included in the request.
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 fails a number of times.
If the response is successful, PCI Vault will try to store the data in the response.
If you would like PCI Vault to smart parse the resulting data,
you can set the smart_parse
flag to true.
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 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" }
],
"status": "200",
"token_info": {
"token": "31fd87cdc5bf9bf13c28684917f9888bf775b07e2f4d8a6ff583ef7c743d2433",
"user": "test3",
"stored_at": "2023-09-06T13:34:06.467787655Z"
}
}
All headers in the third party's response is included.
If smart parsing is active on the request, a censored version of the original response will also be included. The censored version of the response will look like a mustache template.
Please respond with a 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 operation.
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
.