Visa Direct and Mastercard Send — Engineering Real-Time Push Payments

If you've built traditional card payment flows — authorizations, captures, settlements — you already know the pull model inside out. A merchant initiates a request, the issuer approves it, and funds eventually move from cardholder to merchant. Visa Direct and Mastercard Send turn that on its head. Instead of pulling funds from a card, you're pushing funds to a card. And that one directional change cascades into a completely different set of engineering decisions.

I spent the better part of a year integrating both rails into a disbursement platform, and the lessons weren't always in the documentation. Here's what I wish someone had told me upfront.

Pull vs. Push — The Fundamental Shift

In a traditional pull payment, the merchant asks the network to move money from the cardholder's account. In a push payment, the originator sends money directly to a recipient's card. The recipient doesn't need to do anything — the funds just show up. This is why push payments are sometimes called "credit transfers" or Original Credit Transactions (OCTs) in Visa's terminology.

The implications are significant. There's no authorization/capture two-step. There's no chargeback in the traditional sense (though disputes still exist). And the recipient doesn't need to be a merchant — they just need a valid debit card, and in some cases a credit card or prepaid card.

Use Cases That Actually Make Sense

Push payments aren't a replacement for traditional card processing. They solve a specific set of problems where you need to move money to someone quickly:

• Gig economy payouts — Paying drivers, couriers, or freelancers instantly after a job instead of waiting for a weekly ACH batch. This is the killer use case. When we rolled out instant payouts, driver retention improved measurably within the first quarter.
• Insurance claim disbursements — Instead of mailing a check that takes 7-10 days, push the claim payment to the policyholder's debit card in under 30 minutes.
• Refunds-to-card — Faster than the traditional refund flow, which can take 5-10 business days. An OCT refund can post in minutes.
• P2P transfers — The backbone of apps like Venmo and Cash App. When you "instant transfer" to your debit card, that's a push payment under the hood.
• Marketplace seller payouts — Paying sellers on a marketplace platform without waiting for traditional settlement cycles.

Visa Direct OCT — The API Integration

Visa Direct's core primitive is the Original Credit Transaction (OCT). The name is a bit misleading — "credit" here means you're crediting the recipient's account, not that it involves a credit card. In practice, most OCTs target debit cards.

Here's a simplified version of what the OCT request looks like. The real payload has more fields, but these are the ones that matter most:

POST /visadirect/fundstransfer/v1/pushfundstransactions

{
  "systemsTraceAuditNumber": "451050",
  "retrievalReferenceNumber": "412612451050",
  "localTransactionDateTime": "2026-04-17T10:30:00",
  "acquiringBin": "408999",
  "acquirerCountryCode": "840",
  "senderAccountNumber": "4957030420210512",
  "senderName": "Acme Payments Inc",
  "senderCountryCode": "840",
  "transactionCurrencyCode": "USD",
  "recipientPrimaryAccountNumber": "4957030420210496",
  "recipientName": "Jane Doe",
  "amount": "150.00",
  "businessApplicationId": "AA",
  "merchantCategoryCode": "6012",
  "transactionIdentifier": "381228649430015",
  "sourceOfFundsCode": "05"
}

A few things that bit us during integration:

1. The systemsTraceAuditNumber (STAN) must be unique per transaction within a day. We initially used a simple incrementing counter, which broke when we scaled to multiple service instances. Switched to a combination of instance ID and atomic counter — problem solved.
2. Not all cards accept push payments. You need to call the PushFundsTransactions endpoint's companion — the Funds Transfer Inquiry API — to check if a card is eligible before attempting the OCT. Skip this step and you'll see a frustrating ~15% decline rate on first attempts.
3. Timeout handling is critical. If your OCT request times out, you cannot simply retry. The transaction may have gone through on Visa's side. You need to use the retrievalReferenceNumber to query the transaction status before deciding whether to retry. We built a reconciliation worker that runs every 5 minutes to catch these edge cases.

Mastercard Send — Same Concept, Different Mechanics

Mastercard's equivalent is called Mastercard Send (formerly MoneySend). The concept is identical — push funds to a card — but the API surface and some operational details differ enough that you can't just swap one for the other.

Mastercard Send uses a Payment Transfer API. The request structure is similar in spirit but the field names, validation rules, and error codes are all Mastercard-flavored. One notable difference: Mastercard's transferReference serves a similar role to Visa's retrievalReferenceNumber, but the uniqueness constraints and format requirements are different.

Settlement — Where It Gets Interesting

Here's something that confused our finance team initially: the recipient sees the funds almost instantly, but the actual interbank settlement still happens on the network's normal cycle. With Visa Direct, the issuer is essentially fronting the money to the cardholder before settlement completes. This is why Visa's "Fast Funds" program exists — it's an agreement by issuers to make funds available within 30 minutes, even though settlement between the banks happens later.

For your engineering, this means two things. First, your reconciliation system needs to handle the gap between "transaction approved" and "settlement complete." Second, your funding source (the originator's account) gets debited on the settlement cycle, not at transaction time. If you're running a high-volume disbursement platform, you need solid cash flow forecasting to make sure your settlement account can cover the float.

Practical Gotchas from Production

After running push payments in production for over a year, here are the things that don't show up in the happy-path documentation:

Card network tokenization adds a layer

If you're storing card credentials as network tokens (which you should be for PCI scope reduction), be aware that not all token types work with push payments. Visa Direct requires the token to be provisioned with OCT capability. We had a fun week debugging why 8% of our transactions were declining before we figured out the token provisioning was missing the push payment flag.

Cross-border gets complicated fast

Domestic push payments are relatively straightforward. Cross-border introduces currency conversion, additional compliance fields (sender/recipient address, purpose of payment codes), and significantly higher decline rates. Some issuers in certain countries simply don't support inbound push payments. We maintain a country-level eligibility matrix that we update quarterly based on actual transaction data.

Idempotency isn't optional

I've written about idempotency in payment APIs before, but it's worth repeating here. Push payments are non-reversible in most cases. If you accidentally send a duplicate OCT, you can't just void it like a regular authorization. You'd need to initiate a separate Account Funding Transaction (AFT) to pull the funds back — and that requires the recipient's cooperation. Build idempotency into your system from day one. Use the retrievalReferenceNumber as your idempotency key and store it before you even make the API call.

Monitoring needs to be real-time

With traditional payments, a batch reconciliation job running every few hours is usually fine. With push payments, you're moving money in real-time, so your monitoring needs to match. We set up alerts for approval rate drops (anything below 95% triggers a page), unusual transaction velocity, and settlement file discrepancies. The first time our approval rate dropped to 87% on a Saturday morning because an issuer was doing maintenance, we were very glad we had those alerts.

Should You Support Both Networks?

Short answer: yes, if you're building a serious disbursement platform. In the US, roughly 60% of debit cards are Visa and 25% are Mastercard. If you only support Visa Direct, you're telling a quarter of your recipients they can't get instant payouts. We abstracted both networks behind a common interface — the orchestration layer checks the card BIN, determines the network, and routes to the appropriate API. The response normalization layer maps both networks' responses into a unified status model. It's more work upfront, but it pays off quickly.

Push payments are one of those areas where the technology is mature but the institutional knowledge is still catching up. The APIs work. The networks are reliable. The gotchas are in the details — card eligibility, token provisioning, settlement timing, and cross-border compliance. Get those right, and you've got a genuinely powerful tool for moving money fast.

References

• Visa Direct — Visa Developer Center
• Mastercard Send — Mastercard Developers
• Visa Direct Product Page — Visa USA
• Visa Direct API Reference — Push Funds Transactions
• Mastercard Send API Reference

Disclaimer: This article reflects the author's personal experience and opinions. Product names, logos, and brands are property of their respective owners. Pricing and features mentioned are subject to change — always verify with official documentation.