Create payment link on behalf of a store

curl --request POST \
  --url 'https://api.wava.co/v1/links#partners' \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 150000,
  "description": "Monthly subscription - Store ABC",
  "currency": "COP",
  "order_key": "partner-sub-001",
  "redirect_link": "https://partner-platform.com/success"
}
'

const options = {
  method: 'POST',
  headers: {'merchant-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 150000,
    description: 'Monthly subscription - Store ABC',
    currency: 'COP',
    order_key: 'partner-sub-001',
    redirect_link: 'https://partner-platform.com/success'
  })
};

fetch('https://api.wava.co/v1/links#partners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wava.co/v1/links#partners"

payload = {
    "amount": 150000,
    "description": "Monthly subscription - Store ABC",
    "currency": "COP",
    "order_key": "partner-sub-001",
    "redirect_link": "https://partner-platform.com/success"
}
headers = {
    "merchant-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "result": {
    "link": "https://checkout.wava.co/aBcDeFgH",
    "hash": "aBcDeFgH",
    "expires_at": "2025-03-15T23:59:59.000Z",
    "wallet_id": null
  }
}

{
  "code": 4007,
  "api_code": "INVALID_MERCHANT_KEY",
  "message": "Invalid merchant key",
  "description": "The provided merchant key is invalid or expired",
  "error": true
}

{
  "code": 7001,
  "api_code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "description": "An unexpected error occurred while processing your request",
  "error": true
}

Partners

Create payment link on behalf of a store

Partners create payment links for a merchant using that merchant’s merchant-key, delivered to the partner in the store_onboarded webhook. The request body is identical to the standard Create Payment Link endpoint.

The merchant-key is what authorizes the call and what decides which store the link belongs to. Partner credentials may be sent alongside it for attribution, but never change the target store; on their own they are rejected with 403.

The partner relationship is resolved from the merchant’s integration: webhooks for the resulting link are delivered to the partner’s webhook URL.

order_key behaves exactly as on the standard endpoint: it is the identifier of the order on the partner’s side and an idempotency key scoped to (store, order_key), so a repeated order_key may return the existing link instead of creating a new one. Use a unique order_key per buyer.

POST

links#partners

Create payment link on behalf of a store

curl --request POST \
  --url 'https://api.wava.co/v1/links#partners' \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 150000,
  "description": "Monthly subscription - Store ABC",
  "currency": "COP",
  "order_key": "partner-sub-001",
  "redirect_link": "https://partner-platform.com/success"
}
'

const options = {
  method: 'POST',
  headers: {'merchant-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 150000,
    description: 'Monthly subscription - Store ABC',
    currency: 'COP',
    order_key: 'partner-sub-001',
    redirect_link: 'https://partner-platform.com/success'
  })
};

fetch('https://api.wava.co/v1/links#partners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wava.co/v1/links#partners"

payload = {
    "amount": 150000,
    "description": "Monthly subscription - Store ABC",
    "currency": "COP",
    "order_key": "partner-sub-001",
    "redirect_link": "https://partner-platform.com/success"
}
headers = {
    "merchant-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "result": {
    "link": "https://checkout.wava.co/aBcDeFgH",
    "hash": "aBcDeFgH",
    "expires_at": "2025-03-15T23:59:59.000Z",
    "wallet_id": null
  }
}

{
  "code": 4007,
  "api_code": "INVALID_MERCHANT_KEY",
  "message": "Invalid merchant key",
  "description": "The provided merchant key is invalid or expired",
  "error": true
}

{
  "code": 7001,
  "api_code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "description": "An unexpected error occurred while processing your request",
  "error": true
}

Authorizations

merchant-key

string

header

required

Merchant key for store identification. Required for all API requests.

merchant-key: YOUR_MERCHANT_KEY

Body

application/json

description

string

required

Payment description displayed to the buyer.

Required string length: 1 - 255

Example:

"Invoice #1234 - Web design services"

amount

number

Payment amount. Omit this field to create a dynamic link where the buyer enters the amount.

Required range: x >= 0.01

Example:

50000

currency

string

ISO 4217 currency code. Defaults to store currency.

Pattern: ^[A-Z]{3}$

Example:

"COP"

order_key

string

Identifier of the order on your side — not a free-form reference. One order_key = one order = one link = one payment.

It is an idempotency key scoped to (store, order_key): resending an order_key that already has a link on that store does not reliably create a new link. This is the anti-double-charge guarantee. If the existing link is inactive, it is returned as-is and not reactivated; if it already has a confirmed (paid) order, it is returned and no new payment is enabled. Both cases answer 200. No field flags the reuse explicitly, but the response is distinguishable: a reuse response omits expires_at and wallet_id, which a link created by the request always carries (often with a null value, so test for the presence of the key). The hash is not a reliable signal here — it is only returned to requests authenticated with a merchant-key. An explicit 409 is planned behind a feature flag and is not live.

Use a unique order_key per buyer, per order. Keying it on a product or an event (e.g. race-10k for every registration to the same distance) makes every buyer after the first receive the first buyer's link. Omitting order_key is not a workaround: links are keyed on the store plus a hash of the request body, so identical bodies resolve to the same link.

order_key is not the link hash and the hash cannot be derived from it — the hash is computed from the whole request body. Treat the returned link URL and hash as opaque.

Maximum string length: 100

Example:

"inv-1234"

redirect_link

string<uri>

URL to redirect buyer after successful payment.

Example:

"https://mystore.com/thanks"

redirect_link_cancel

string<uri>

URL to redirect buyer if payment is cancelled.

Example:

"https://mystore.com/cancelled"

redirect_link_failure

string<uri>

URL to redirect buyer if payment fails.

Example:

"https://mystore.com/error"

collect_shopper_data

boolean

default:false

When true, the checkout page prompts the buyer for contact information (first name, last name, email, phone number) before proceeding to payment method selection. The submitted data is stored with the order.

Only valid on dynamic links (requests without an amount). Setting this to true on a fixed-amount link returns a 400 error.

Example:

true

wallet_id

integer | null

Wava balance wallet this link's payments should credit — the merchant's account inside Wava, not the buyer's payment method.

Omit it to credit the merchant's default wallet for the link's currency. This is the normal case: most merchants hold a single wallet per currency.

Only merchants with multiple wallets enabled can bind a link. For any other merchant the field is ignored and the response echoes wallet_id: null.

Rejections: 404 WALLET_NOT_FOUND if the wallet does not belong to the merchant, 400 CURRENCY_MISMATCH if its currency differs from the link's, 422 WALLET_NOT_ACTIVE if it is suspended or closed.

Example:

4712

Response

Payment link created on behalf of store

result

object

Show child attributes

API Reference

Endpoints

Create payment link on behalf of a store

Authorizations

Body

Response