Resolve a customer credential to a CustomerContext

curl --request POST \
  --url https://api.feddi.io/v1/partner/identify \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "meta": {
    "partner_request_id": "7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6",
    "occurred_at": "2026-06-05T10:00:00Z",
    "sent_at": "2026-06-05T10:00:01Z",
    "api_version": "2026-06-01"
  },
  "context": {
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "branch_id": "22222222-2222-2222-2222-222222222222",
    "terminal_id": "POS-360-0001",
    "cashier_id": "cashier-7",
    "partner_session_id": null,
    "feddi_session_id": null
  },
  "credential": {
    "credential_type": "phone",
    "phone": "+97433001122"
  }
}
'

import requests

url = "https://api.feddi.io/v1/partner/identify"

payload = {
    "meta": {
        "partner_request_id": "7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6",
        "occurred_at": "2026-06-05T10:00:00Z",
        "sent_at": "2026-06-05T10:00:01Z",
        "api_version": "2026-06-01"
    },
    "context": {
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "branch_id": "22222222-2222-2222-2222-222222222222",
        "terminal_id": "POS-360-0001",
        "cashier_id": "cashier-7",
        "partner_session_id": None,
        "feddi_session_id": None
    },
    "credential": {
        "credential_type": "phone",
        "phone": "+97433001122"
    }
}
headers = {
    "x-api-key": "<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>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    meta: {
      partner_request_id: '7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6',
      occurred_at: '2026-06-05T10:00:00Z',
      sent_at: '2026-06-05T10:00:01Z',
      api_version: '2026-06-01'
    },
    context: {
      merchant_id: '11111111-1111-1111-1111-111111111111',
      branch_id: '22222222-2222-2222-2222-222222222222',
      terminal_id: 'POS-360-0001',
      cashier_id: 'cashier-7',
      partner_session_id: null,
      feddi_session_id: null
    },
    credential: {credential_type: 'phone', phone: '+97433001122'}
  })
};

fetch('https://api.feddi.io/v1/partner/identify', 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.feddi.io/v1/partner/identify",
  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([
    'meta' => [
        'partner_request_id' => '7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6',
        'occurred_at' => '2026-06-05T10:00:00Z',
        'sent_at' => '2026-06-05T10:00:01Z',
        'api_version' => '2026-06-01'
    ],
    'context' => [
        'merchant_id' => '11111111-1111-1111-1111-111111111111',
        'branch_id' => '22222222-2222-2222-2222-222222222222',
        'terminal_id' => 'POS-360-0001',
        'cashier_id' => 'cashier-7',
        'partner_session_id' => null,
        'feddi_session_id' => null
    ],
    'credential' => [
        'credential_type' => 'phone',
        'phone' => '+97433001122'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-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.feddi.io/v1/partner/identify"

	payload := strings.NewReader("{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}")

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

	req.Header.Add("x-api-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.feddi.io/v1/partner/identify")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.feddi.io/v1/partner/identify")

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["Content-Type"] = 'application/json'
request.body = "{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}"

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

{
  "ok": true,
  "data": {
    "resolution_state": "registered",
    "wallet_user_id": "wu-aabbccdd-1234",
    "wallet_program_id": "wp-55667788-0001",
    "wallet_id": "wlt-99001122-ffff",
    "identity_trace_id": "idt-trace-xyzabc",
    "display_name": "Ahmed Al-Rashid",
    "badge": "Gold",
    "balance": {
      "actual_minor": 15000,
      "promo_available_minor": 500,
      "promo_locked_minor": 1200,
      "pending_topups_minor": 0,
      "currency": "QAR",
      "promo_grants": [
        {
          "source": "CASHBACK",
          "state": "RELEASED",
          "remaining_minor": 500,
          "expires_at": "2026-09-05T00:00:00Z"
        },
        {
          "source": "RELOAD_BONUS",
          "state": "LOCKED",
          "remaining_minor": 1200,
          "expires_at": "2026-09-10T00:00:00Z"
        }
      ]
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_b2c3d4",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 88,
    "decision_trace_id": null
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

platform

Resolve a customer credential to a CustomerContext

The canonical identity-resolution resource. Accepts one of five credential types (discriminated by credential_type: phone | card_fingerprint | short_code | provider_customer_id | qr) and resolves the customer to a CustomerContext carrying their wallet state, promo balance, wallet program binding, and an identity_trace_id for downstream correlation. Returns one of three resolution states: registered (fully enrolled, balance readable), pending_proof (enrolled but not yet identity-verified, balance visible but spend gated by the POS), or not_found (no wallet identity for this credential under this enterprise). A credential that matches a customer enrolled in multiple active programs returns WALLET_PROGRAM_AMBIGUOUS (HTTP 422); the error body lists the candidates so the caller can present a disambiguator. This endpoint never returns a debit token, an authorization token, or any artifact that permits a ledger mutation. The session-anchored variant, which writes the resolved identity into an open checkout session, is POST /checkout/sessions/{id}/identify. Use this standalone endpoint for balance-check panels, cashier lookup screens, and POS-display use cases where there is no active checkout session. Rate-limited per integration to prevent enumeration attacks; a 429 response carries Retry-After and X-RateLimit-* headers.

POST

identify

curl --request POST \
  --url https://api.feddi.io/v1/partner/identify \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "meta": {
    "partner_request_id": "7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6",
    "occurred_at": "2026-06-05T10:00:00Z",
    "sent_at": "2026-06-05T10:00:01Z",
    "api_version": "2026-06-01"
  },
  "context": {
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "branch_id": "22222222-2222-2222-2222-222222222222",
    "terminal_id": "POS-360-0001",
    "cashier_id": "cashier-7",
    "partner_session_id": null,
    "feddi_session_id": null
  },
  "credential": {
    "credential_type": "phone",
    "phone": "+97433001122"
  }
}
'

import requests

url = "https://api.feddi.io/v1/partner/identify"

payload = {
    "meta": {
        "partner_request_id": "7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6",
        "occurred_at": "2026-06-05T10:00:00Z",
        "sent_at": "2026-06-05T10:00:01Z",
        "api_version": "2026-06-01"
    },
    "context": {
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "branch_id": "22222222-2222-2222-2222-222222222222",
        "terminal_id": "POS-360-0001",
        "cashier_id": "cashier-7",
        "partner_session_id": None,
        "feddi_session_id": None
    },
    "credential": {
        "credential_type": "phone",
        "phone": "+97433001122"
    }
}
headers = {
    "x-api-key": "<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>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    meta: {
      partner_request_id: '7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6',
      occurred_at: '2026-06-05T10:00:00Z',
      sent_at: '2026-06-05T10:00:01Z',
      api_version: '2026-06-01'
    },
    context: {
      merchant_id: '11111111-1111-1111-1111-111111111111',
      branch_id: '22222222-2222-2222-2222-222222222222',
      terminal_id: 'POS-360-0001',
      cashier_id: 'cashier-7',
      partner_session_id: null,
      feddi_session_id: null
    },
    credential: {credential_type: 'phone', phone: '+97433001122'}
  })
};

fetch('https://api.feddi.io/v1/partner/identify', 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.feddi.io/v1/partner/identify",
  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([
    'meta' => [
        'partner_request_id' => '7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6',
        'occurred_at' => '2026-06-05T10:00:00Z',
        'sent_at' => '2026-06-05T10:00:01Z',
        'api_version' => '2026-06-01'
    ],
    'context' => [
        'merchant_id' => '11111111-1111-1111-1111-111111111111',
        'branch_id' => '22222222-2222-2222-2222-222222222222',
        'terminal_id' => 'POS-360-0001',
        'cashier_id' => 'cashier-7',
        'partner_session_id' => null,
        'feddi_session_id' => null
    ],
    'credential' => [
        'credential_type' => 'phone',
        'phone' => '+97433001122'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-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.feddi.io/v1/partner/identify"

	payload := strings.NewReader("{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}")

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

	req.Header.Add("x-api-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.feddi.io/v1/partner/identify")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.feddi.io/v1/partner/identify")

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["Content-Type"] = 'application/json'
request.body = "{\n  \"meta\": {\n    \"partner_request_id\": \"7f3a1e20-1b2c-4d5e-8f90-a1b2c3d4e5f6\",\n    \"occurred_at\": \"2026-06-05T10:00:00Z\",\n    \"sent_at\": \"2026-06-05T10:00:01Z\",\n    \"api_version\": \"2026-06-01\"\n  },\n  \"context\": {\n    \"merchant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"branch_id\": \"22222222-2222-2222-2222-222222222222\",\n    \"terminal_id\": \"POS-360-0001\",\n    \"cashier_id\": \"cashier-7\",\n    \"partner_session_id\": null,\n    \"feddi_session_id\": null\n  },\n  \"credential\": {\n    \"credential_type\": \"phone\",\n    \"phone\": \"+97433001122\"\n  }\n}"

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

{
  "ok": true,
  "data": {
    "resolution_state": "registered",
    "wallet_user_id": "wu-aabbccdd-1234",
    "wallet_program_id": "wp-55667788-0001",
    "wallet_id": "wlt-99001122-ffff",
    "identity_trace_id": "idt-trace-xyzabc",
    "display_name": "Ahmed Al-Rashid",
    "badge": "Gold",
    "balance": {
      "actual_minor": 15000,
      "promo_available_minor": 500,
      "promo_locked_minor": 1200,
      "pending_topups_minor": 0,
      "currency": "QAR",
      "promo_grants": [
        {
          "source": "CASHBACK",
          "state": "RELEASED",
          "remaining_minor": 500,
          "expires_at": "2026-09-05T00:00:00Z"
        },
        {
          "source": "RELOAD_BONUS",
          "state": "LOCKED",
          "remaining_minor": 1200,
          "expires_at": "2026-09-10T00:00:00Z"
        }
      ]
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_b2c3d4",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 88,
    "decision_trace_id": null
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "ok": true,
  "meta": {
    "request_id": "<string>",
    "api_version": "2026-06-01",
    "idempotency_replayed": true,
    "data_completeness_score": 50,
    "decision_trace_id": "<string>",
    "capabilities": {}
  },
  "data": {},
  "error": {
    "message": "<string>",
    "details": {}
  }
}

Authorizations

x-api-key

string

header

required

Partner API key (platform- or merchant-scoped). Contract key-enforces context.merchant_id.

Headers

Idempotency-Key

string<uuid>

OPTIONAL on this operation, it is a side-effect-free read behind a POST (the body carries the query). Reads are naturally idempotent, so no dedup key is required for correctness. If you send the header anyway (e.g. uniform client middleware that stamps every POST), it is accepted and replays are reported via meta.idempotency_replayed. Mutating operations use the REQUIRED IdempotencyKey parameter instead.

Body

application/json

Body for POST /identify. Carries exactly one credential (discriminated by credential.credential_type). No checkout session context is required, this is the standalone identify. For the session-anchored variant use POST /checkout/sessions/{id}/identify.

Response

Customer resolved. Inspect data.resolution_state for the resolution outcome: registered, pending_proof, or not_found. The not_found state is returned as HTTP 200 with a null balance (not 404) so polling UIs can distinguish 'no wallet' from a server error.

The standard response envelope that every enveloped endpoint serializes through. ok is a boolean discriminator: when ok is true, the typed result is carried in data; when ok is false, a typed error object is returned instead. The meta object is uniform across the entire API surface.

boolean

required

Overview

Endpoints

Resolve a customer credential to a CustomerContext

Authorizations

Headers

Body

Response