API to update the state or metadata of a payment
Actions
When updating a payment there are different actions that can be executed:
- ACCEPT: to confirm a pending payment created by the users
- CANCEL: to cancel a pending payment
- CANCEL_OR_REFUND: to request a payment to be either canceled if still pending or refunded if already accepted
REFUND vs CANCEL payments
A payment can be updated to CANCELED only if it hasn't been ACCEPTED yet.
If an ACCEPTED payment needs to be refunded you need to create a payment with a REFUND flow.
RETRY
If the API returns any of the possible error, like a 500, this doesn't mean that the payment might not be ACCEPTED already.
If you get the error we suggest to execute a retry within few seconds and if still not getting a response execute an Update Payment with the CANCEL_OR_REFUND flow.
CANCEL_OR_REFUND
We strongly suggest to execute an Update payment with action CANCEL_OR_REFUND whenever you are not able to get the status of a payment.
This might be caused by either Satispay being temporarily unavailable or network issues.
Executing a CANCEL_OR_REFUND we avoid the case of a user who confirms a payment, the payment is accepted but you do not issue the product to the user.
Responses
200 OK
- id [string]: Unique ID of the payment.
- type [string]: Type of payment (
TO_BUSINESS
) - amount_unit [number]: Amount of the payment in cents
- currency [string]: Currency of the payment
- status [string]: Status of the payment (
ACCEPTED
orCANCELED
) - expired [boolean]: If true, the payment is expired
- metadata [object]: Additional metadata of the payment
- sender [object]: The sender actor of the payment
- id [string]: Unique ID of the sender
- type [string]: Type of the actor (
CONSUMER
) - name [string]: Short name of the actor
- receiver [object]: The receiver actor of the payment
- id [string]: Unique ID of the receiver
- type [string]: Type of the actor (
SHOP
)
- daily_closure [object]: The daily closure of the payment
- id [string]: ID of the daily closure
- date [string]: The closure date
- insert_date [datetime]: Timestamp of payment insertion
- expire_date [datetime]: Timestamp of payment expiration
- external_code [string]: Order ID or payment external identifier
400 Bad request
- code [integer]: Error code
36
→ invalid query parament status - message [string]: Error message
401 Unauthorized
- code [integer]: Error code
34
→ shop not found or unauthorized - message [string]: Error message
403 Forbidden or invalid authorization header
- code [integer]: Error code
44
→ illegal state transition
45
→ unable to fulfil request
70
→ anti-hammering violation - message [string]: Error message
404 Resource not found
- code [integer]: Error code
- message [string]: Error message