API to update the state or metadata of a payment


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.



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.



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.


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 or CANCELED)
  • 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