Back to Developer Portal
Payments API

Payments API Reference

Start payment flows and get payment URLs to redirect users to Waffy's secure payment interface. Supports multiple payment methods as configured per organization.

Overview

The Payments API allows you to initiate payment flows by generating secure payment URLs. Users are redirected to Waffy's payment interface where they can complete payments using the payment methods configured for your organization. Right before the redirect, your backend asks for a payment ticket for the buyer; the whole flow is in Build a payment, Payment.

Multiple Methods

Mada, Visa, Mastercard, Apple Pay, STC Pay, Tabby, Tamara, Neo and manual bank transfer, as enabled on your organization

Hosted checkout

Customers pay on Waffy's page and come back to your redirect URL

Webhooks

Status changes are sent to your webhook URL

Recommended: Use Payment SDK

For better integration experience and additional features, we recommend using our Payment SDK instead of the direct API calls.

View SDK Documentation

GETStart Payment

Generate a payment URL to redirect users to Waffy's payment interface

Endpoint

GET /api/external/contracts/startPayment/%milestone_contract_id%/%merchant_client_id%

Query Parameters

ParameterTypeRequiredDescription
redirectUrlstringfalseURL to redirect user after payment completion
paymentTypestringfalseType of payment (AUTHORIZE_CAPTURE or PURCHASE)

Example Request

GET /api/external/contracts/startPayment/%milestone_contract_id%/%merchant_client_id%?redirectUrl=https://example.com/success&paymentType=PURCHASE

Response (200 OK)

{
  "status": 200,
  "timestamp": "2026-01-20T18:32:12.563788",
  "data": "https://external.waffyapp.com/external/domainId?client_id=%merchant_client_id%&redirect_url=https://example.com/success&paymentType=PURCHASE&payment_methods=MANUAL_BANK_TRANSFER,MOYASAR,TABBY,APPLE_PAY"
}

Common Errors

404 Not Found - Contract Not Found

{
  "status": 404,
  "timestamp": "2026-01-20T18:52:22.831103",
  "error": {
    "status": "NOT_FOUND",
    "message": "Contract was not found for parameters {id={{milestone_contract_id}}}"
  }
}

400 Bad Request - Payment Not Allowed

{
  "status": 400,
  "timestamp": "2026-01-20T18:53:53.015276",
  "error": {
    "status": "BAD_REQUEST",
    "message": "Payment not allowed on contract with id {{milestone_contract_id}} because it is in an un-payable status RESOLVED_REFUND_CUSTOMER.."
  }
}

Payment Flow

How to integrate the payment URL into your application

1
Call Start Payment API
Make a GET request with contract ID and required parameters
2
Redirect User
Redirect the user to the URL in the data field of the response
3
User Completes Payment
User selects payment method and completes payment on Waffy's secure interface
4
User Redirected Back
After payment completion, user is redirected to your specified redirectUrl

After the payment

Where the result shows up

Start Payment has no payment status of its own. Once the customer pays, the contract status changes, for example to PAYMENT_PROCESSING while a payment is in progress and to PAID when it is done, and your webhook is called. Read the contract with GET /api/external/contracts/{contract_id} or wait for the webhook; see the Webhooks page.

Payment Integration Guide

Learn how to integrate payments into your application

View Guide

Test Cards

Test card numbers for the sandbox

View Test Cards