Attribute an unattributed payment
Runs allocation again for a payment the gateway approved but that was never allocated to a charge, so it stops sitting in UNATTRIBUTED and settles the contract's charges. It works only on the contract the payment already belongs to: it cannot move a payment to a different account or contract, and it makes no gateway call of its own. Optionally it sends the payer the receipt the payment should have produced. A payment reaches UNATTRIBUTED when the gateway approved it and the allocation that follows then failed (the money was taken, nothing was settled); it is also the intermediate state of an approved status override (Mark an unresolved payment approved or declined) and of a capture (Capture an authorised payment).
Where you can do this
- Merchant View: Transaction (Attribute)
Before you start
- The transaction exists and its status is UNATTRIBUTED.
- Its contract and its account still exist.
- The contract has charges in SETUP, ACTIVE, FAILING or ERROR whose open parts belong to the transaction's account and carry the transaction's legal entity (or none at all), together covering the whole amount. Charges on any other contract are never considered.
- No instance option or feature gates this function.
Rules
Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.
| Rule | Checked by | What you see |
|---|---|---|
:id must be a transaction id, with or without the tr_ prefix; unlike the refund routes an alt_key is not resolved here and reaches Shuttle as an unknown id | The API | INVALID (BOLT-1143) |
| The transaction must exist | The API | INVALID (BOLT-1143) |
| The transaction must be UNATTRIBUTED | The API | INVALID (BOLT-1144) |
| The amount is allocated to the charges of the transaction's own contract, earliest due first, and only to parts that are still open, belong to the same account and match the transaction's legal entity. The payment cannot be pointed at another account, contract or charge | The API | none; no input can ask for it |
| One attribution of a transaction at a time; the call waits up to 30 seconds for a concurrent attribution to finish | The API | INVALID (BOLT-7059) |
| Post-submission fraud screening runs again whenever the payment carries workflow hooks and did not already end in a stop verdict. A suspend verdict ends the payment PENDING instead of SUCCESS; a fresh stop verdict ends it ROLLBACK and returns the money through the gateway (an authorisation is voided instead) | The API | HTTP 200; the payment comes back PENDING or ROLLBACK, and on a stop the money goes back to the payer |
| The contract's stored payment method is replaced with the one this payment used, whether or not it differs | The API | none |
| The payer is notified only when the payment ends SUCCESS for an amount above zero; a payment held as PENDING sends nothing at the time | The API | none; no receipt |
What happens
- The call answers HTTP 200 with the transaction. Read its
status: SUCCESS means the money is now settled against the contract's charges, PENDING means it is held (the gateway had answered pending, or fraud screening suspended it), UNATTRIBUTED means nothing happened and there is no error to read. - On success the amount clears the contract's charges earliest due first; each part, instalment and charge it fully covers is completed; the contract moves out of SETUP, FAILING, ERROR or UNRESOLVED to ACTIVE (PENDING when the payment is held), its completed and paid totals rise and its last payment becomes this one. Its failure count and exhausted-retry flag are cleared, so a contract that had been chased for arrears stops being chased.
- The contract's stored payment method is set to the one this payment used, and the account's last transaction, last activity and division list are updated.
notify_usertrue sends the payer the payment receipt for a successful attribution; from Merchant View that always happens.- Webhooks: PAYMENT.SUCCESS (PAYMENT.PENDING when held), ACCOUNT.UPDATE, CONTRACT.UPDATE, CONTRACT.START when the contract was still being set up, CHARGE.COMPLETE for each charge cleared, and a further CONTRACT.UPDATE when the payment method changed. None of the contract and charge events are raised for a one-off due at once.
- A payment that came from a payment link marks that link completed and raises PAYMENT_LINK.COMPLETE.
Who can do this
- Roles: Admin only.
- Admin app options: none; the control sits behind no instance option and is offered whenever the status is UNATTRIBUTED.
Related
Updated about 6 hours ago