Create Pre-Debit Notification - Yuno API Documentation

POST

predebit-notify

Create Pre-Debit Notification

curl --request POST \
  --url https://api-sandbox.y.uno/v1/predebit-notify \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "merchant_reference": "subscription-2026-08-INV-00187",
  "description": "Your subscription renews soon",
  "amount": {
    "currency": "INR",
    "value": "499.00"
  },
  "billing_date": "2026-08-01",
  "billing_sequence_number": "2",
  "customer_payer": {
    "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  },
  "payment_method": {
    "type": "UPI_AUTOPAY",
    "vaulted_token": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "provider_data": {
    "id": "EBANX",
    "connection_id": "6c1f6bfb-736b-439e-b568-32f671f65256"
  }
}
'

import requests

url = "https://api-sandbox.y.uno/v1/predebit-notify"

payload = {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "merchant_reference": "subscription-2026-08-INV-00187",
    "description": "Your subscription renews soon",
    "amount": {
        "currency": "INR",
        "value": "499.00"
    },
    "billing_date": "2026-08-01",
    "billing_sequence_number": "2",
    "customer_payer": { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" },
    "payment_method": {
        "type": "UPI_AUTOPAY",
        "vaulted_token": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    },
    "provider_data": {
        "id": "EBANX",
        "connection_id": "6c1f6bfb-736b-439e-b568-32f671f65256"
    }
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '00000000-0000-0000-0000-000000000000',
    merchant_reference: 'subscription-2026-08-INV-00187',
    description: 'Your subscription renews soon',
    amount: {currency: 'INR', value: '499.00'},
    billing_date: '2026-08-01',
    billing_sequence_number: '2',
    customer_payer: {id: '9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d'},
    payment_method: {type: 'UPI_AUTOPAY', vaulted_token: '7c9e6679-7425-40de-944b-e07fc1f90ae7'},
    provider_data: {id: 'EBANX', connection_id: '6c1f6bfb-736b-439e-b568-32f671f65256'}
  })
};

fetch('https://api-sandbox.y.uno/v1/predebit-notify', 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://api-sandbox.y.uno/v1/predebit-notify",
  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([
    'account_id' => '00000000-0000-0000-0000-000000000000',
    'merchant_reference' => 'subscription-2026-08-INV-00187',
    'description' => 'Your subscription renews soon',
    'amount' => [
        'currency' => 'INR',
        'value' => '499.00'
    ],
    'billing_date' => '2026-08-01',
    'billing_sequence_number' => '2',
    'customer_payer' => [
        'id' => '9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d'
    ],
    'payment_method' => [
        'type' => 'UPI_AUTOPAY',
        'vaulted_token' => '7c9e6679-7425-40de-944b-e07fc1f90ae7'
    ],
    'provider_data' => [
        'id' => 'EBANX',
        'connection_id' => '6c1f6bfb-736b-439e-b568-32f671f65256'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "private-secret-key: <api-key>",
    "public-api-key: <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://api-sandbox.y.uno/v1/predebit-notify"

	payload := strings.NewReader("{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}")

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

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<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://api-sandbox.y.uno/v1/predebit-notify")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/predebit-notify")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "merchant_reference": "<string>",
  "description": "<string>",
  "amount": {
    "currency": "INR",
    "value": "499.00"
  },
  "billing_date": "2023-12-25",
  "origin_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "provider_data": {
    "id": "<string>",
    "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "provider_transaction_id": "<string>",
    "provider_notification_id": "<string>",
    "raw_request": {},
    "raw_response": {}
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Before each UPI Autopay recurring debit, NPCI requires notifying the customer in advance. This endpoint sends that notice through the payment provider and returns an id you must reference on the debit. The flow has three steps:

Notify: call this endpoint with the mandate’s vaulted_token, the upcoming amount, and the billing_date. Provider routing comes from origin_payment_id (the mandate-creation payment) or an explicit provider_data.
Check the status: SENT means the provider delivered the notification and returned its reference in provider_data.provider_notification_id.
Debit: create the recurring payment with payment_method.detail.bank_transfer.pre_debit_notification_id set to the returned id. Yuno resolves the provider reference and forwards it automatically — see Create payment.

This request requires an X-Idempotency-Key. Reusing a merchant_reference returns the existing notification for your account.

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Headers

X-Idempotency-Key

string

required

Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts.

Body

application/json

account_id

string<uuid>

required

Your Yuno account ID.

merchant_reference

string

required

Your unique reference for this notification. Reusing a reference returns the existing notification (idempotent per account).

amount

object

required

Show child attributes

billing_date

string<date>

required

Date of the upcoming debit (YYYY-MM-DD). Per NPCI, notify the customer at least 24 hours before the debit.

description

string

Text shown to the customer in the notification (for example, the subscription name and renewal notice).

billing_sequence_number

string

Sequence number of the debit within the mandate (for example, 2 for the second charge).

origin_payment_id

string<uuid>

ID of the mandate-creation payment. When provided, Yuno derives the provider and connection from its successful charge. Either origin_payment_id or provider_data is required.

customer_payer

object

Show child attributes

payment_method

object

Show child attributes

provider_data

object

Explicit provider routing. Either origin_payment_id or provider_data (id + connection_id) is required.

Show child attributes

Response

Notification created. Check status: SENT means the provider delivered it.

string<uuid>

Unique identifier of the pre-debit notification. Reference it on the recurring debit as payment_method.detail.bank_transfer.pre_debit_notification_id.

account_id

string<uuid>

Your Yuno account ID.

status

enum<string>

SENT: the provider accepted and delivered the notification. REJECTED: the provider refused it. ERROR: the notification could not be relayed.

Available options:

SENT,

REJECTED,

ERROR

merchant_reference

string

Your unique reference for this notification (idempotent per account).

description

string

Text shown to the customer in the notification.

amount

object

Show child attributes

billing_date

string<date>

Date of the upcoming debit (YYYY-MM-DD).

origin_payment_id

string<uuid>

The mandate-creation payment used to derive provider and connection, when provided.

provider_data

object

Show child attributes

created_at

string<date-time>

updated_at

string<date-time>

Retrieve Pre-Debit Notification by IDRetrieve a pre-debit notification by its Yuno ID.

⌘I

Create Pre-Debit Notification

curl --request POST \
  --url https://api-sandbox.y.uno/v1/predebit-notify \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "merchant_reference": "subscription-2026-08-INV-00187",
  "description": "Your subscription renews soon",
  "amount": {
    "currency": "INR",
    "value": "499.00"
  },
  "billing_date": "2026-08-01",
  "billing_sequence_number": "2",
  "customer_payer": {
    "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  },
  "payment_method": {
    "type": "UPI_AUTOPAY",
    "vaulted_token": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "provider_data": {
    "id": "EBANX",
    "connection_id": "6c1f6bfb-736b-439e-b568-32f671f65256"
  }
}
'

import requests

url = "https://api-sandbox.y.uno/v1/predebit-notify"

payload = {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "merchant_reference": "subscription-2026-08-INV-00187",
    "description": "Your subscription renews soon",
    "amount": {
        "currency": "INR",
        "value": "499.00"
    },
    "billing_date": "2026-08-01",
    "billing_sequence_number": "2",
    "customer_payer": { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" },
    "payment_method": {
        "type": "UPI_AUTOPAY",
        "vaulted_token": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    },
    "provider_data": {
        "id": "EBANX",
        "connection_id": "6c1f6bfb-736b-439e-b568-32f671f65256"
    }
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '00000000-0000-0000-0000-000000000000',
    merchant_reference: 'subscription-2026-08-INV-00187',
    description: 'Your subscription renews soon',
    amount: {currency: 'INR', value: '499.00'},
    billing_date: '2026-08-01',
    billing_sequence_number: '2',
    customer_payer: {id: '9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d'},
    payment_method: {type: 'UPI_AUTOPAY', vaulted_token: '7c9e6679-7425-40de-944b-e07fc1f90ae7'},
    provider_data: {id: 'EBANX', connection_id: '6c1f6bfb-736b-439e-b568-32f671f65256'}
  })
};

fetch('https://api-sandbox.y.uno/v1/predebit-notify', 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://api-sandbox.y.uno/v1/predebit-notify",
  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([
    'account_id' => '00000000-0000-0000-0000-000000000000',
    'merchant_reference' => 'subscription-2026-08-INV-00187',
    'description' => 'Your subscription renews soon',
    'amount' => [
        'currency' => 'INR',
        'value' => '499.00'
    ],
    'billing_date' => '2026-08-01',
    'billing_sequence_number' => '2',
    'customer_payer' => [
        'id' => '9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d'
    ],
    'payment_method' => [
        'type' => 'UPI_AUTOPAY',
        'vaulted_token' => '7c9e6679-7425-40de-944b-e07fc1f90ae7'
    ],
    'provider_data' => [
        'id' => 'EBANX',
        'connection_id' => '6c1f6bfb-736b-439e-b568-32f671f65256'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "private-secret-key: <api-key>",
    "public-api-key: <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://api-sandbox.y.uno/v1/predebit-notify"

	payload := strings.NewReader("{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}")

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

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<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://api-sandbox.y.uno/v1/predebit-notify")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/predebit-notify")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n  \"merchant_reference\": \"subscription-2026-08-INV-00187\",\n  \"description\": \"Your subscription renews soon\",\n  \"amount\": {\n    \"currency\": \"INR\",\n    \"value\": \"499.00\"\n  },\n  \"billing_date\": \"2026-08-01\",\n  \"billing_sequence_number\": \"2\",\n  \"customer_payer\": {\n    \"id\": \"9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d\"\n  },\n  \"payment_method\": {\n    \"type\": \"UPI_AUTOPAY\",\n    \"vaulted_token\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  },\n  \"provider_data\": {\n    \"id\": \"EBANX\",\n    \"connection_id\": \"6c1f6bfb-736b-439e-b568-32f671f65256\"\n  }\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "merchant_reference": "<string>",
  "description": "<string>",
  "amount": {
    "currency": "INR",
    "value": "499.00"
  },
  "billing_date": "2023-12-25",
  "origin_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "provider_data": {
    "id": "<string>",
    "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "provider_transaction_id": "<string>",
    "provider_notification_id": "<string>",
    "raw_request": {},
    "raw_response": {}
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}