Skip to content
Sitora Docs

payments_device_handoff_report

POST
/api/payments/v1/devices/assignment/report/
curl --request POST \
  --url https://example.com/api/payments/v1/devices/assignment/report/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "intent_id": 1, "outcome": "reported_success", "provider_reference": "example", "provider_code": "example", "client_idempotency_key": "example" }'

Report the outcome the payment application returned for an assigned intent. Idempotent under client_idempotency_key. The intent moves to processing whatever the reported outcome — a device cannot settle or decline money; the cashier attests or cancels on this evidence.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
object
intent_id
required
integer
outcome
required
  • reported_success - Payment app reported success
  • reported_declined - Payment app reported a decline
  • reported_cancelled - Payment app reported a cancellation
  • reported_unknown - Outcome unknown to the payment app
string
Allowed values: reported_success reported_declined reported_cancelled reported_unknown
provider_reference
string
<= 64 characters
provider_code
string
<= 64 characters
client_idempotency_key
string
<= 128 characters

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
report
required

A payment application’s reported outcome — evidence, never truth.

Rendered beside the settle affordance so the cashier attests over machine corroboration instead of a blank field. outcome is machine vocabulary; clients label it themselves.

object
outcome
required
string
provider_reference
required
string
provider_code
required
string
reported_at
required
string format: date-time
assignment
required

The collection a companion has been handed. Backend-authored.

Every money field here is order truth snapshotted at creation; a device supplies none of it and can amend none of it.

object
intent_id
required
integer
intent_display_number
required
integer
order_display_number
required
integer
station_name
required
string
amount
required
string format: decimal
/^-?\d{0,10}(?:\.\d{0,2})?$/
currency
required
string
status
required
string
handoff_target
required
string
expires_at
required
string format: date-time
Examplegenerated
{
  "report": {
    "outcome": "example",
    "provider_reference": "example",
    "provider_code": "example",
    "reported_at": "2026-04-15T12:00:00Z"
  },
  "assignment": {
    "intent_id": 1,
    "intent_display_number": 1,
    "order_display_number": 1,
    "station_name": "example",
    "amount": "example",
    "currency": "example",
    "status": "example",
    "handoff_target": "example",
    "expires_at": "2026-04-15T12:00:00Z"
  }
}

503

Section titled “503”

This deployment cannot store or read protected Handbook content because DJANGO_KNOWLEDGE_CONTENT_KEY is unset or unusable. Answered by the platform exception handler rather than by this endpoint, so any path can return it; retrying does not help until an operator fixes the deployment.

Media typeapplication/json

This deployment cannot store or read protected Handbook content because DJANGO_KNOWLEDGE_CONTENT_KEY is unset or unusable. Answered by the platform exception handler rather than by this endpoint, so any path can return it; retrying does not help until an operator fixes the deployment.

object
code
required
string
Allowed values: content_key_missing
detail
required
string
Example
{
  "code": "content_key_missing"
}