Developer Docs

Prefill API

Create a checkout from your server. How the payment flow works, then the endpoint, request, response, errors and code examples.

Docs menuPrefill API
Quick Start Setup & Credentials Prefill API Opening the Checkout Phones & In-App Browsers Webhooks Paying Your Users Reconciliation Environments Common Mistakes Go-Live Checklist FAQ

How It Works

Customer's browser Your server RocketRamp 1. Clicks "Pay with RocketRamp" 2. POST prefill (Merchant-ID, API-Key) 3. { "embed_code": "..." } save embed_code + customer 4. embed_code 5. Opens app.myrocketramp.com/embed/<embed_code> and pays 6. Signed webhook: embed_transfer, success 7. Verify, match embed_code, credit once per transfer_id, 200
  1. The customer clicks "Pay with RocketRamp" on your site. Your page calls your own server.
  2. Your server calls the Prefill API with the recipient email, and your Merchant ID and API Key in the headers.
  3. The API returns an embed_code. Your server saves it next to the customer and the order, then returns it to the page.
  4. 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.
  5. The customer signs in to RocketRamp, chooses the amount and pays.
  6. RocketRamp sends a webhook to your server with type: "embed_transfer", status: "success", the amount, the transfer_id and the embed_code.
  7. Your server verifies the webhook, finds the customer by embed_code, credits them once, and replies 200.
Closing the checkout is not a payment

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

HTTP
POST https://api.vantack.com/v1/merchants/embed/prefill

Headers

HeaderValue
Merchant-IDYour Merchant ID (the UUID, without any prefix)
API-KeyYour API Key, in plain text exactly as issued
Content-Typeapplication/json

Request body

FieldTypeRequiredDescription
emailstringYesThe RocketRamp account that receives the money: your business's RocketRamp email. To pay a user, use Disbursements, not a prefill.
memostringNoA short note, returned in the webhook. Do not put personal data in it.
amountnumberNoLeave it out for deposits; the payer chooses the amount in the checkout. Send it only for a fixed bill.
metadataobjectNoYour own tags, kept by RocketRamp with the checkout. The webhook does not return it, so never use it to find the customer.
JSON
{
  "email": "payments@your-business.example.com",
  "memo":  "Deposit for order 1234"
}

Response: 200 OK

JSON
{
  "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

ResponseCause and fix
Invalid API Key or Merchant mismatchThe 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 permissionThe key is valid but cannot create checkouts. Create a key with the wallet_embed:write permission.
Timeout or HTTP 5xxNo 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.

Node.js (18+, Express)
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 });
});
PHP
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'];
}
Python (Flask)
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
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"}
?