Create an Israeli direct debit authorization

Credentials

Overview

Availability. Israeli Direct Debit is offered to high-volume sellers only. It is enabled per account after approval by your PayMe sales representative; it is not self-service. Until then, generate-sale returns 720.

Israeli direct debit works in two phases:

  1. Set up the bank authorization (this page): the buyer signs a debit authorization on PayMe's page, and PayMe saves it as a token (buyer_key).
  2. Charge the authorization with buyer_key.

POST https://sandbox.payme.io/api/generate-sale (production: https://live.payme.io/api/generate-sale), with a JSON body (Content-Type: application/json).

Set up the authorization

Call generate-sale with sale_type: token and sale_payment_method: il-direct-debit. Show the returned sale_url to the buyer: the page collects the account owner's identity, the bank account and a signature. Nothing is charged; the setup sale is always created with a price of 100.

The token stays inactive until the bank confirms the authorization. Wait for the callbacks below before you charge it.

Credentials

Send seller_payme_id (the MPL) in the JSON body: this endpoint doesn't read the PayMe-Merchant-Key header, so a request without a body MPL returns error 1. Partners add payme_client_key (or the PayMe-Partner-Key header) and may name the seller by seller_id instead. See Authentication.

Callbacks

PayMe sends form-encoded callbacks to sale_callback_url:

  1. sale-complete – the bank approved the authorization; the token (buyer_key) is now active and can be charged. sale-failure – the bank rejected it.
  2. sale-il-direct-debit-update – the authorization status, with authorization_status, authorization_error_code, buyer_name and buyer_key, plus the usual sale fields.
notify_type=sale-il-direct-debit-update&payme_sale_id=SALE1700-000000AA-EXAMPLE1-SALE0001&sale_status=completed&authorization_status=1&authorization_error_code=&buyer_key=BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567&buyer_name=First%20Last&…

The authorization_status values are on Errors → Israeli direct debit. The bank can revoke an authorization later; the token then becomes inactive and charges fail.

Testing

Sandbox bank accounts are on Test Cards and Payment Methods. In the sandbox you receive only authorization statuses 1 (success) and 2 (failure).

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Field Type Required Description
seller_payme_id string yes The seller's MPL, in the JSON body. The authorization is given to this seller.
payme_client_key string no Partners only: your partner key (or send the PayMe-Partner-Key header). With seller_payme_id, the seller must belong to you, otherwise error 20.
sale_type string yes Must be token.
sale_payment_method string yes Must be il-direct-debit.
sale_price integer yes Any numeric value. The setup sale is always created with 100 and nothing is charged. A missing or non-numeric value returns 352.
currency string no Send ILS. Without it the account's default currency is used.
product_name string yes Any short description, for example Direct debit authorization. It doesn't affect the setup. Missing returns 353.
transaction_id string no Your own order reference, up to 50 characters. PayMe returns it in responses and callbacks but doesn't check it for uniqueness.
sale_callback_url string no Where PayMe sends the sale-complete / sale-failure and sale-il-direct-debit-update callbacks. If omitted, your partner's default callback URL is used, if one is set; a seller has no dashboard setting for it, so send it. Must be a public address: localhost, private or loopback IP addresses and IPv6 addresses are refused with error 21, which fails the whole call.
sale_return_url string no Where PayMe redirects the buyer after the setup page. Same address rules as sale_callback_url (error 21).
language string no Language of the payment page and the error messages. Default he. he and en are fully supported; es, ru and ar are accepted, but messages and the payment page are then mostly in English. Case-insensitive; any other value, or an empty string, returns error 51.

Request example

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_type": "token",
  "sale_payment_method": "il-direct-debit",
  "sale_price": 100,
  "currency": "ILS",
  "product_name": "Direct debit authorization",
  "transaction_id": "ildd-setup-1001",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/ildd/done",
  "language": "en"
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/generate-sale' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_type": "token",
  "sale_payment_method": "il-direct-debit",
  "sale_price": 100,
  "currency": "ILS",
  "product_name": "Direct debit authorization",
  "transaction_id": "ildd-setup-1001",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/ildd/done",
  "language": "en"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/generate-sale", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sale_type": "token",
    "sale_payment_method": "il-direct-debit",
    "sale_price": 100,
    "currency": "ILS",
    "product_name": "Direct debit authorization",
    "transaction_id": "ildd-setup-1001",
    "sale_callback_url": "https://your-server.example.com/payme/callback",
    "sale_return_url": "https://your-site.example.com/ildd/done",
    "language": "en"
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-sale",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "sale_type": "token",
        "sale_payment_method": "il-direct-debit",
        "sale_price": 100,
        "currency": "ILS",
        "product_name": "Direct debit authorization",
        "transaction_id": "ildd-setup-1001",
        "sale_callback_url": "https://your-server.example.com/payme/callback",
        "sale_return_url": "https://your-site.example.com/ildd/done",
        "language": "en",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_type": "token",
  "sale_payment_method": "il-direct-debit",
  "sale_price": 100,
  "currency": "ILS",
  "product_name": "Direct debit authorization",
  "transaction_id": "ildd-setup-1001",
  "sale_callback_url": "https://your-server.example.com/payme/callback",
  "sale_return_url": "https://your-site.example.com/ildd/done",
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/generate-sale');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

200 — Setup sale created (success)

Field Type Description
status_code integer 0 success, 1 error.
sale_url string PayMe's payment page for this sale. Show it to the buyer in an iframe or a redirect, exactly as returned. It stays payable while the sale is initial or failed, until sale_expiry_seconds passes if you sent it.
payme_sale_id string PayMe's sale ID. Store it: refunds, captures and queries use it.
payme_sale_code integer Short numeric sale code, for display only.
price integer Sale amount in minor units (100 for a token sale).
transaction_id string Your order reference, as sent.
currency string Sale currency (ISO 4217).
sale_payment_method string Payment method of the sale, for example credit-card or multi.
session string Request ID. Quote it when you contact PayMe. 
{
  "status_code": 0,
  "session": "AtsJ0as5",
  "sale_url": "https://sandbox.payme.io/sale/generate/SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_id": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_code": 12345678,
  "price": 100,
  "transaction_id": "ildd-setup-1001",
  "currency": "ILS",
  "sale_payment_method": "il-direct-debit"
}

500 — Request refused. Most request errors return HTTP 500 with status_code: 1; some return 400, 403, 422 or 429. See Errors. (error)

Field Type Description
status_code integer 1 for an error.
status_error_code integer PayMe's error code, for example 251 (seller not found) or 352 (invalid price).
status_error_details string The error message, in the requested language (Hebrew by default).
status_additional_info string Extra detail, usually the name of the field at fault.
session string Request ID. Quote it when you contact PayMe. 
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "AtsJ0as5"
}