Generate Bank Link

cURL

curl --request POST \
  --url https://sandbox.zapyd.com/cms/api/v1/bank/generate-link \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-SIGNATURE: <api-key>' \
  --header 'X-TIMESTAMP: <api-key>' \
  --data '
{
  "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
  "redirect_url": "https://yourapp.com/bank/return"
}
'

import requests

url = "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link"

payload = {
    "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
    "redirect_url": "https://yourapp.com/bank/return"
}
headers = {
    "X-API-KEY": "<api-key>",
    "X-TIMESTAMP": "<api-key>",
    "X-SIGNATURE": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'X-TIMESTAMP': '<api-key>',
    'X-SIGNATURE': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'c2cf861b-342b-4318-a90e-85cd0312e82f',
    redirect_url: 'https://yourapp.com/bank/return'
  })
};

fetch('https://sandbox.zapyd.com/cms/api/v1/bank/generate-link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => 'c2cf861b-342b-4318-a90e-85cd0312e82f',
    'redirect_url' => 'https://yourapp.com/bank/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>",
    "X-SIGNATURE: <api-key>",
    "X-TIMESTAMP: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link"

	payload := strings.NewReader("{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("X-TIMESTAMP", "<api-key>")
	req.Header.Add("X-SIGNATURE", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.zapyd.com/cms/api/v1/bank/generate-link")
  .header("X-API-KEY", "<api-key>")
  .header("X-TIMESTAMP", "<api-key>")
  .header("X-SIGNATURE", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.zapyd.com/cms/api/v1/bank/generate-link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-TIMESTAMP"] = '<api-key>'
request["X-SIGNATURE"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "message": "Success",
  "data": {
    "widget_url": "https://link.example.com/session/7f3c2a9e"
  }
}

{
  "status": false,
  "message": "Bad Request",
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "redirect_url": [
      "This field is required."
    ]
  }
}

POST

bank

generate-link

cURL

curl --request POST \
  --url https://sandbox.zapyd.com/cms/api/v1/bank/generate-link \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-SIGNATURE: <api-key>' \
  --header 'X-TIMESTAMP: <api-key>' \
  --data '
{
  "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
  "redirect_url": "https://yourapp.com/bank/return"
}
'

import requests

url = "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link"

payload = {
    "customer_id": "c2cf861b-342b-4318-a90e-85cd0312e82f",
    "redirect_url": "https://yourapp.com/bank/return"
}
headers = {
    "X-API-KEY": "<api-key>",
    "X-TIMESTAMP": "<api-key>",
    "X-SIGNATURE": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'X-TIMESTAMP': '<api-key>',
    'X-SIGNATURE': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'c2cf861b-342b-4318-a90e-85cd0312e82f',
    redirect_url: 'https://yourapp.com/bank/return'
  })
};

fetch('https://sandbox.zapyd.com/cms/api/v1/bank/generate-link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => 'c2cf861b-342b-4318-a90e-85cd0312e82f',
    'redirect_url' => 'https://yourapp.com/bank/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>",
    "X-SIGNATURE: <api-key>",
    "X-TIMESTAMP: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.zapyd.com/cms/api/v1/bank/generate-link"

	payload := strings.NewReader("{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("X-TIMESTAMP", "<api-key>")
	req.Header.Add("X-SIGNATURE", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.zapyd.com/cms/api/v1/bank/generate-link")
  .header("X-API-KEY", "<api-key>")
  .header("X-TIMESTAMP", "<api-key>")
  .header("X-SIGNATURE", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.zapyd.com/cms/api/v1/bank/generate-link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["X-TIMESTAMP"] = '<api-key>'
request["X-SIGNATURE"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"c2cf861b-342b-4318-a90e-85cd0312e82f\",\n  \"redirect_url\": \"https://yourapp.com/bank/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "message": "Success",
  "data": {
    "widget_url": "https://link.example.com/session/7f3c2a9e"
  }
}

{
  "status": false,
  "message": "Bad Request",
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "redirect_url": [
      "This field is required."
    ]
  }
}

Generate Bank Link

Open in Cursor

How linking works

Your backend calls this endpoint for a VERIFIED US customer and gets widget_url.
Your app opens widget_url. The customer signs in to their bank and picks the account.
The customer lands on redirect_url, whether linking worked or not.
Call Fetch Bank Accounts. The account is in accounts, PROCESSING until the connection completes, then VERIFIED. No BANK webhook is sent, so poll.
Create an ACH_PULL payin quotation with that account’s id as bank_id. It’s required: without it the quotation fails with No linked bank account found for the selected payment method. Zapyd debits that account, so there are no deposit instructions.

In sandbox, the hosted page isn’t available for test customers. Call Mock Bank Verification with the US customer_id, bank_status: "VERIFIED" and no bank_id: it creates a linked test account that Fetch Bank Accounts returns.

Error Codes and Messages

API Status Code	Response	Reason
400	This field is required.	`customer_id` or `redirect_url` is missing
400	Enter a valid URL.	`redirect_url` isn’t a full URL
400	”<value>” is not a valid payment_method. Expected one of: wire, debit_card, ach_pull.	`payment_method` isn’t one of the listed values
400	Customer not found or access denied.	Customer not found, or not in your organization
500	Internal Server Error	The customer hasn’t completed US KYC, or the link couldn’t be created. Check the customer is `VERIFIED` before retrying

Authorizations

X-API-KEY

string

header

required

API Key for authentication

X-TIMESTAMP

string

header

required

Current timestamp in seconds since epoch

X-SIGNATURE

string

header

required

HMAC SHA256 signature of the request encoded in Base64

Body

application/json

customer_id

string<uuid>

required

Zapyd customer ID (UUID) of a VERIFIED US customer.

Example:

"c2cf861b-342b-4318-a90e-85cd0312e82f"

redirect_url

string<uri>

required

Where the customer returns after linking, whether it worked or not. Must be a full URL.

Example:

"https://yourapp.com/bank/return"

payment_method

enum<string>

default:ach_pull

Optional. The payin method the account is linked for. Defaults to ach_pull. Case-insensitive.

Available options:

ach_pull,

wire,

debit_card

Example:

"ach_pull"

Response

Link created

status

boolean

Example:

true

message

string

Example:

"Success"

data

object

Hide child attributes

Hosted bank-linking page. Open it in a browser or webview; it expires, so create a new one for each attempt.

Example:

"https://link.example.com/session/7f3c2a9e"

Using the API

Onboarding

Money movement

Platform

Sandbox

Generate Bank Link

How linking works

Error Codes and Messages

Authorizations

Body

Response

​How linking works

​Error Codes and Messages

Authorizations

Body

Response

How linking works

Error Codes and Messages