Disbursements

Apple Pay disbursements invert the standard payment flow — instead of a customer paying you, you send funds to a card stored in the recipient's Apple Wallet. The recipient authorises the payout with Face ID, Touch ID, or passcode, and the funds are pushed directly to their card.

Use casesAskCopy

For standard refunds tied to an original VINR payment, use the Refunds API instead.

How disbursements workAskCopy

1. Your server initiates a disbursement request via the VINR Disbursements API.
2. VINR presents the Apple Pay payout sheet on the recipient's device (in your app or website).
3. The recipient authenticates with Face ID, Touch ID, or passcode.
4. Apple returns an encrypted payout token to VINR.
5. VINR decrypts the token and pushes the funds to the recipient's card via the card network.
6. You receive a disbursement.succeeded webhook when funds are sent.

Create a disbursementAskCopy

curl https://api.vinr.com/v1/disbursements \
  -u YOUR_SECRET_KEY: \
  -d "amount=5000" \
  -d "currency=usd" \
  -d "description=Winnings payout" \
  -d "recipient[name]=Jane Smith" \
  -d "payout_method_types[]=apple_pay"

The response includes a client_secret used to present the payout sheet on the client.

Present the payout sheetAskCopy

const vinr = Vinr('pk_live_...');

// Create a Disbursement Intent server-side, then use its client_secret
const { error, disbursement } = await vinr.confirmApplePayDisbursement(
  disbursementIntentClientSecret,
  {
    applePay: {
      lineItems: [
        { label: 'Winnings', amount: '50.00', type: 'final' },
      ],
      total: {
        label: 'Your payout',
        amount: '50.00',
        type: 'final',
      },
    },
  }
);

if (error) {
  console.error(error.message);
} else {
  // disbursement.status === 'processing' or 'succeeded'
}

import VinrSDK

let disbursement = VinrDisbursement(
    clientSecret: "di_client_secret_...",
    amount: NSDecimalNumber(string: "50.00"),
    currency: "usd",
    label: "Your payout"
)

VinrAPI.shared.confirmApplePayDisbursement(disbursement) { result in
    switch result {
    case .success(let disbursementResult):
        print("Payout status: \(disbursementResult.status)")
    case .failure(let error):
        print("Payout failed: \(error.localizedDescription)")
    }
}

Supported payout networksAskCopy

Apple Pay disbursements are supported on Visa and Mastercard debit and prepaid cards in supported markets. Credit cards are not supported for disbursements.

Check card eligibility before presenting the payout sheet — cards that don't support push-to-card will return an error at the network level.

Webhook eventsAskCopy

{
  "type": "disbursement.succeeded",
  "data": {
    "object": {
      "id": "di_123",
      "amount": 5000,
      "currency": "usd",
      "status": "succeeded",
      "payout_method": "apple_pay",
      "recipient": {
        "name": "Jane Smith"
      },
      "created": 1704067200
    }
  }
}

Limits and complianceAskCopy

• Maximum payout amount per transaction: determined by your account configuration and the recipient's card issuer.
• Disbursements are subject to AML and sanctions screening. VINR performs this automatically; abnormal patterns may trigger a review.
• Recipients in sanctioned countries cannot receive disbursements. VINR returns a disbursement_blocked error in these cases.
• If your platform disburses on behalf of connected accounts, pass on_behalf_of with the connected account ID.

Test disbursementsAskCopy

Use test API keys and a real card on a test device. VINR intercepts the Apple Pay token in test mode and simulates a successful payout without moving real funds.

To simulate a failed payout, use the test card number designated for disbursement failure in your VINR Dashboard test data.

See alsoAskCopy