What can we help you with?

Enabling Online Refunds


What are online refunds?

Online refunds refers to the new refund.authorization messages that Visa, Mastercard and Discover merchants can now send to card issuers. These refund authorizations allow merchants to notify customers earlier of a pending refund, and to give card issuers the opportunity to decline a refund. This functionality is currently disabled for all Marqeta environments, and will be selectively enabled for you after coordinating with your Marqeta contacts.

Like purchase authorizations, refund authorizations are eventually ‘cleared’ or completed by a refund.authorization.clearing event. That refund authorization clearing is automatically accepted and processed by the Marqeta platform, regardless of your funding model. This is the same way ‘offline’ refunds are currently processed, and there will be no changes to this behavior.

Also similar to a purchase authorization, it is possible for a refund authorization to expire (if the refund authorization clearing is never received), though this is an edge case. A refund authorization that fails to clear within seven days is unlikely to ever be completed.

What am I required to do?

All programs will need to be aware of the new event types that will be received by your webhook endpoint.

If your Marqeta program is using only pre-funded cards, or uses a Managed JIT funding model, then you will not need to make any changes to accept online refunds. However, you may need to do work for your system to be informed about these events as they are sent through to your webhook endpoint.

If your Marqeta program is using a Gateway JIT funding model, you will be required to respond to a new type of message that will be sent to your JIT funding gateway endpoint or those online refunds will be declined. Mastercard programs are already receiving these messages today and they are currently being declined. Marqeta is in the process of implementing support for Mastercard online refunds, but customer should be ready to respond once the messages start arriving to their gateway.


Support for refund.authorization messages is still being built into our Marqeta Sandbox environment simulation suite. Prepare your gateway endpoint to always approve these refund.authorization requests and conduct your final tests in the production environment.

Please coordinate with your Marqeta customer success contact to make sure that your platform is ready to receive these new online refund messages, and to have online refunds enabled for your environment (Mastercard programs are already receiving this online refund message by default). If your gateway isn’t able to approve these new refund authorization messages, it will result in those refunds being declined. When the merchant receives a decline for their refund authorization request, they will likely issue an out-of-band refund via store credit, an alternate payment method, or cash. Therefore, it is important that Marqeta only enables online refunds for your environment after you’ve made the supporting changes on your end.


For Visa and Discover programs, Marqeta will not start sending you the refund authorization messages until your platform is ready to receive them. Until then, a workaround is in place with the network to make sure that online refunds are always approved.

For Mastercard programs, Marqeta is already receiving refund authorization messages, but we do not yet support taking action on them. All online refund requests for Mastercard programs are being declined until we are certified with Mastercard, due early Q2. In the meantime, JIT gateway Mastercard customers should be prepared to respond to online refund requests so they're ready when MQ's support for this feature goes live.

Because online refund events cannot be simulated, your ability to see refund.authorizations in the system will be determined by merchant adoption/usage.

If you would like to start building logic based on these events, please make sure that your webhook endpoint is setup to process the new event type. 


Supporting online refunds requires some development work if you are currently using a JIT funding gateway to approve/decline transactions in real-time.  If you do not use a JIT funding gateway, and you use a pre-funded or managed JIT funding model, then there is no required development work to approve the refund authorization requests. 

Regardless of funding model, there may be work required to parse/ingest this new event type at your webhook endpoint.

JIT Gateway

Your gateway is currently configured to respond to authorizations and their corresponding JIT funding requests in order to approve them. A new event type, refund.authorization, will be sent to your JIT Gateway and a response message needs to be returned. Just like with purchase authorizations, refund authorizations must be approved or else the eventual refund.authorization.clearing event will be sent by the merchant (refund will not go through to the original form of payment).

Only the refund authorization is actionable, and requires a response from your JIT gateway. The authorization event will also be received by your webhook endpoint upon completion.

  • refund.authorization (pgfs.refund.authorization)

These online refund events below are not sent to your gateway, as they are not actionable:

  • refund.authorization.advice
  • refund.authorization.clearing
  • refund.authorization.reversal 

For more information from our documentation site, you can find “refund.authorization” on the following page:


Example funding request

Example funding message that your JIT gateway will be receiving. Similar to ‘normal’, offline refunds, there is no direct association between this refund and the original purchase/clearing. Also note that there is a new pgfs method in the payload.

"token": "1824bae9-d9a4-4018-a617-c3c7600cb7eb",
  "method": "pgfs.refund.authorization",
  "user_token": "a_user_1",
  "acting_user_token": "a_user_1",
  "amount": 12.34

Example funding response

Your gateway will respond with the expected 200 HTTP status and JSON body containing the jit_funding object. Similar to JIT funding requests for purchase authorizations, the jit_funding in your response will mirror the jit_funding object you originally received. 

Please note that the ‘amount’ should always match the original amount requested (there is no partial authorization behavior).


"token": "1824bae9-d9a4-4018-a617-c3c7600cb7eb",
  "method": "pgfs.refund.authorization",
  "user_token": "a_user_1",
  "acting_user_token": "a_user_1",
  "amount": 12.34
  “tags”: “tag1, tag2”, //optional
  “memo”: “order #1234” //optional

Non-gateway (pre-funded or managed JIT)

If your cards are all prefunded or you use a managed JIT funding model, then online refunds will be automatically approved. There is no work required in this case to support online refund transactions.


Once a refund.authorization is approved, you will receive a webhook message for this event. As with other webhook messages, you can build business logic to trigger customer notifications or pending ledger entries in response to the refund.authorization being received.

These are the new event types you’ll receive webhooks for:

  • refund.authorization
  • refund.authorization.advice
  • refund.authorization.clearing
  • refund.authorization.reversal

Transaction flow

Refund authorization and clearing

  1. refund.authorization
  2. refund.authorization.clearing

Refund authorization, adjustment, and clearing

  1. refund.authorization
  2. refund.authorization.advice
  3. refund.authorization.clearing

Refund authorization and reversal

  1. refund.authorization
  2. refund.authorization.reversal
    1. Refund.authorization.reversal (merchant initiated)
    2. refund.authorization.reversal.issuerexpiration (default is 8 days)


  1. Inform your Marqeta Customer Success contact when you have made the appropriate changes to support online refunds. For gateway customers, this means having your platform return an approval response if a refund.authorization or refund.authorization.advice is received. For non-gateway customers, there is no preparation needed.
  2. Your Marqeta Customer Success contact will inform you once:
    1. the appropriate changes have been made within your Marqeta program configuration to enable online refunds. For Mastercard programs, this will occur only once Marqeta's support is also live.
    2. the appropriate changes have been made at the card network so that online refund requests will start to be sent to your Marqeta environment.
  3. As online refunds start to be received, please inform your Marqeta contact if you encounter any issues in processing the new events, and we can start the process to rollback changes if needed.
Thanks for the feedback
Thanks for the feedback
Was this article helpful?

We've recieved your feedback.

Contact Developer Support
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.