How It Works
- The customer clicks "Pay with RocketRamp" on your site. Your page calls your own server.
- Your server calls the Prefill API with the recipient email, and your Merchant ID and API Key in the headers.
- The API returns an
embed_code. Your server saves it next to the customer and the order, then returns it to the page. - Your page opens
https://app.myrocketramp.com/embed/<embed_code>. On desktop it opens in a modal on your page. On phones it opens as its own page. The recipient is already filled in. - The customer signs in to RocketRamp, chooses the amount and pays.
- RocketRamp sends a webhook to your server with
type: "embed_transfer",status: "success", the amount, thetransfer_idand theembed_code. - Your server verifies the webhook, finds the customer by
embed_code, credits them once, and replies 200.
Never credit a customer because the checkout closed or they came back to your page. Only the webhook confirms money.
Prefill API: Endpoint, Request & Response
Call this from your backend only. It needs your private API Key.
Endpoint
POST https://api.vantack.com/v1/merchants/embed/prefillHeaders
| Header | Value |
|---|---|
Merchant-ID | Your Merchant ID (the UUID, without any prefix) |
API-Key | Your API Key, in plain text exactly as issued |
Content-Type | application/json |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The RocketRamp account that receives the money: your business's RocketRamp email. To pay a user, use Disbursements, not a prefill. |
memo | string | No | A short note, returned in the webhook. Do not put personal data in it. |
amount | number | No | Leave it out for deposits; the payer chooses the amount in the checkout. Send it only for a fixed bill. |
metadata | object | No | Your own tags, kept by RocketRamp with the checkout. The webhook does not return it, so never use it to find the customer. |
{
"email": "payments@your-business.example.com",
"memo": "Deposit for order 1234"
}Response: 200 OK
{
"embed_code": "ca678360-5ae6-4f6b-be1d-8583c02447cb",
"status": "created"
}The embed_code is a UUID for one checkout. Save it before you return it to the browser, in a row with the customer, the order, the time and status pending. That row is how you find the customer when the webhook arrives. If the save fails, do not hand out the code.
Errors
| Response | Cause and fix |
|---|---|
Invalid API Key or Merchant mismatch | The key and Merchant ID are not from the same account, or the key was altered (for example, still encrypted). Send the matching pair. |
API key lacks wallet_embed:write permission | The key is valid but cannot create checkouts. Create a key with the wallet_embed:write permission. |
| Timeout or HTTP 5xx | No money moved; prefill only creates a checkout. Ask the customer to try again. |
Show customers a plain message such as "We could not start the payment. Please try again." Log the API's exact response on your server only.
Code Examples
Each example creates a checkout on the server, saves the embed_code, and returns it to the browser. Read credentials from environment variables.
app.post('/api/rocketramp/checkout', requireLogin, async (req, res) => {
const r = await fetch('https://api.vantack.com/v1/merchants/embed/prefill', {
method: 'POST',
headers: {
'Merchant-ID': process.env.ROCKETRAMP_MERCHANT_ID,
'API-Key': process.env.ROCKETRAMP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
email: process.env.ROCKETRAMP_RECIPIENT_EMAIL,
memo: `Deposit by customer ${req.user.id}`,
}),
signal: AbortSignal.timeout(10000),
});
const data = await r.json().catch(() => ({}));
if (r.status !== 200 || !data.embed_code) {
console.error('prefill refused', r.status, data);
return res.status(502).json({ error: 'Could not start the payment. Please try again.' });
}
await db.query(
"INSERT INTO rr_checkouts (embed_code, customer_id, status, created_at) VALUES ($1, $2, 'pending', now())",
[data.embed_code, req.user.id]);
res.json({ embed_code: data.embed_code });
});function rocketramp_checkout(PDO $db, int $customerId): ?string {
$ch = curl_init('https://api.vantack.com/v1/merchants/embed/prefill');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => [
'Merchant-ID: ' . getenv('ROCKETRAMP_MERCHANT_ID'),
'API-Key: ' . getenv('ROCKETRAMP_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'email' => getenv('ROCKETRAMP_RECIPIENT_EMAIL'),
'memo' => 'Deposit by customer ' . $customerId,
]),
]);
$body = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode((string)$body, true);
if ($http !== 200 || empty($data['embed_code'])) {
error_log('prefill refused: ' . $http . ' ' . substr((string)$body, 0, 300));
return null;
}
$db->prepare("INSERT INTO rr_checkouts (embed_code, customer_id, status, created_at)
VALUES (?, ?, 'pending', NOW())")
->execute([$data['embed_code'], $customerId]);
return $data['embed_code'];
}import os, requests
@app.post("/api/rocketramp/checkout")
@login_required
def rocketramp_checkout():
r = requests.post(
"https://api.vantack.com/v1/merchants/embed/prefill",
headers={
"Merchant-ID": os.environ["ROCKETRAMP_MERCHANT_ID"],
"API-Key": os.environ["ROCKETRAMP_API_KEY"],
"Content-Type": "application/json",
},
json={"email": os.environ["ROCKETRAMP_RECIPIENT_EMAIL"],
"memo": f"Deposit by customer {current_user.id}"},
timeout=10,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if r.status_code != 200 or not data.get("embed_code"):
app.logger.error("prefill refused %s %s", r.status_code, r.text[:300])
return {"error": "Could not start the payment. Please try again."}, 502
db.execute("INSERT INTO rr_checkouts (embed_code, customer_id, status, created_at) "
"VALUES (%s, %s, 'pending', now())", (data["embed_code"], current_user.id))
return {"embed_code": data["embed_code"]}curl -X POST https://api.vantack.com/v1/merchants/embed/prefill \
-H "Merchant-ID: YOUR_MERCHANT_ID" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"payments@your-business.example.com","memo":"Deposit for order 1234"}'
# {"embed_code":"ca678360-5ae6-4f6b-be1d-8583c02447cb","status":"created"}