детальный разбор логики работы API и структуры ответов

🔑 Key Identifiers (Ключевые идентификаторы)

Для отслеживания транзакций используются три типа ID:

  • globalId: АAPI task identifier (Идентификатор задачи в системе).
  • paysendId: Payment identifier generated by Paysend (Внутренний ID платежа Paysend).
  • invoiceId: Payment identifier provided by Client (Ваш уникальный номер заказа).

🔄 Scenario 1: Pay To Card Regular Flow

Этот сценарий описывает стандартный процесс обработки платежа.

Step 1: Payment initiation

  • Action: Client sends POST /processing/pay.toCard(payment instruction).
  • Response: Accepted containing a globalId.

Step 2: Polling via globalId (task)

  • Frequency: Every 5 seconds until the task is finished.
  • Method: GET /processing/status/{globalId}.
  • Logic (alt):
    • If task.status == Accepted: Continue polling until another status is received.
    • If task.status == Success (code 0) OR Error (code NOT in 5, 999, 9999): Stop polling as the Final outcome is reached. Set status to Completed or Declined in your system.
    • If task.status == Error (code in 5, 999, 9999): The task is finished, but the payment status is not final yet (OnHold / ManualResolve).

Step 3: Polling via paysendId (payment)

Если на предыдущем этапе получен код 5, 999 или 9999, необходимо сменить метод отслеживания.

  • Wait: 5 minutes before switching.
  • Method: POST /processing/task.statusGet using paysendId.
  • Frequency: Low frequency (2-3 times per day).
  • Terminal Statuses: Completed, Declined, or Refunded indicate the final outcome.

⚠️ Scenario 2: Pay To Card Failure Flow

Используется, если на запрос инициации платежа не был получен ответ.

  1. Wait: 5 minutes to allow the transaction to reach the database.
  2. Polling via invoiceId: Call POST /processing/task.statusGet using your invoiceId.
  3. Analysis:
    • If Error Code 3006 (Transaction not found): The transaction was not created. You can safely repeat the payment with the same invoiceId.
    • If status in (OnHold, InProgress): Continue polling (every 1 hour or 2-3 times per day) until the final status is reached.
    • If status in (Completed, Declined): Final Payment Status reached.

📊 Response Examples Analysis (Разбор JSON-ответов)

Response TypeTask Result StatusTask Result CodePayload Task Result StatusPayload Task Result CodeComment / Action [cite]
SuccessfulFinished2Success0Payment Completed.
RFI (OnHold)Finished2Error5"Offline Antifraud check: RFI". Transaction put OnHold.
ErrorFinished2Error1000 (or other)"Processing error occurred". Transaction Declined Immediately.
AmbiguousFinished2Error999 or 9999"Timeout". Status unknown. Must use task.statusGet.

Important Data Fields in JSON:

  • arn / rrn: Retrieval Reference Numbers (только при успехе).
  • rate: Exchange rate applied to the transaction.
  • statusUri: Link to check task status.
  • duplicate protection: If an invoiceId is reused for a successful payment, the new one will be placed OnHold.