Payouts

Send money directly to a recipient's debit or credit card with card payouts (Original Credit Transactions).

A card payout, or Original Credit Transaction (OCT), pushes funds to a recipient's Visa or Mastercard card. The recipient doesn't need to share a bank account. Typical uses are insurance claims, payments to gig workers, marketplace sellers and winnings.

Payouts use the payment method credit-card-oct and are only available in a server-to-server integration, because you collect the card details yourself.

Activation and PCI DSS

Payouts must be activated for your account. Because card numbers pass through your systems, you need to be PCI DSS compliant, as for any server-to-server card integration.

Pay out to a new card

A payout to a card that isn't in the vault yet takes three requests:

Step	Request	Purpose
1	`POST https://api.dev.gingerpayments.com/v1/orders/`	Create the payout order and transaction.
2	`POST https://tokens.dev.gingerpayments.com/v1/cards/`	Store the card in the vault and get a `vault_token`.
3	`POST https://api.dev.gingerpayments.com/v1/orders/{order_id}/transactions/{transaction_id}/authenticate/`	Execute the payout.

Create the payout order

Create an order with one credit-card-oct transaction:

curl https://api.dev.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "PAYOUT-001",
    "description": "Example card payout",
    "webhook_url": "https://www.example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card-oct"
      }
    ],
    "customer": {
      "merchant_customer_id": "123456789",
      "email_address": "user@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 0AA",
      "city": "London",
      "country": "GB",
      "locale": "en",
      "phone_numbers": ["+441234566788"],
      "ip_address": "192.168.0.1"
    }
  }'

The response contains the order and transaction IDs, and a setup_token for the next step:

{
  "id": "44ba8743-c1aa-4c3a-ac4f-559a271af3e2",
  "status": "new",
  "transactions": [
    {
      "id": "a2b70660-bb80-4ca8-9f50-fa50795c20c8",
      "credit_debit": "debit",
      "payment_method": "credit-card-oct",
      "payment_method_details": {
        "setup_token": "2b938795-316c-4d35-a872-65c3f4a4378e"
      },
      "status": "new",
      "transaction_type": "oct"
    }
  ]
}

Store the card in the vault

Send the card details and the setup_token to the card vault. The setup_token can be used only once and expires 300 seconds after it was issued.

curl https://tokens.dev.gingerpayments.com/v1/cards/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "John Smith",
    "pan": "4111111111111111",
    "expiry": "012030",
    "setup_token": "2b938795-316c-4d35-a872-65c3f4a4378e"
  }'

{
  "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
  "truncated_pan": "4111********1111",
  "brand": "visa",
  "brands": ["visa"]
}

Store the vault_token if you want to pay out to the same card again later.

Execute the payout

Assign the vault_token to the transaction. The cvc is optional for payouts.

curl https://api.dev.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/authenticate/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3"
  }'

{
  "redirect_url": "https://api.dev.gingerpayments.com/redirect/44ba8743-c1aa-4c3a-ac4f-559a271af3e2/a2b70660-bb80-4ca8-9f50-fa50795c20c8/completed/"
}

There's no customer interaction for a payout. Retrieve the order with a status request, or wait for the webhook, to get the final result.

Pay out to a saved card

If you already have a vault_token for the card, add it to the transaction when you create the order. The payout is executed right after the order is created, in a single request:

curl https://api.dev.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "PAYOUT-002",
    "description": "Example card payout",
    "webhook_url": "https://www.example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card-oct",
        "payment_method_details": {
          "vault_token": "796c1201-6f8b-44ce-99ac-8b0648a3553a"
        }
      }
    ],
    "customer": {
      "merchant_customer_id": "123456789",
      "email_address": "user@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 0AA",
      "city": "London",
      "country": "GB",
      "phone_numbers": ["+441234566788"],
      "ip_address": "192.168.0.1"
    }
  }'

A successful payout looks like this when you retrieve the order:

{
  "id": "56ef495f-a61b-426d-8d36-b787c8bcdfed",
  "currency": "EUR",
  "amount": 995,
  "status": "completed",
  "transactions": [
    {
      "id": "e137784c-f343-4e07-8652-e2e9b520080c",
      "payment_method": "credit-card-oct",
      "payment_method_details": {
        "consumer_country": "US",
        "vault_token": "796c1201-6f8b-44ce-99ac-8b0648a3553a"
      },
      "status": "accepted",
      "transaction_type": "oct"
    }
  ]
}

Fields

Order

Field	Required	Description
`currency`	Yes	ISO 4217 currency code, such as `EUR`, `GBP` or `SEK`.
`amount`	Yes	Amount in the smallest currency unit: `1234` is 12.34. Not every currency has two decimals: some have three or none.
`merchant_order_id`	Yes	Your own reference for the payout.
`description`	Yes	Description of the payout.
`transactions[].payment_method`	Yes	Must be `credit-card-oct`.
`webhook_url`	No	Where status changes are sent.

Customer

Field	Required	Description
`merchant_customer_id`	Yes	Your own reference for the recipient.
`email_address`	Yes	Recipient's email address.
`first_name`	Yes	Recipient's first name, 1 to 120 characters.
`last_name`	Yes	Recipient's last name, 1 to 120 characters.
`address_type`	Yes	Must be `billing`.
`address`	Yes	Street and house number, 1 to 120 characters.
`postal_code`	Yes	Postal code, 1 to 10 uppercase letters and digits, optionally with one space.
`city`	Yes	City, 1 to 120 characters.
`state`	Conditional	Two-letter state, province or territory code. Required for the United States, Canada and Australia. See Account funding for the US and Canadian codes.
`country`	Yes	ISO 3166-1 alpha-2 country code, such as `GB`.
`phone_numbers`	Yes	Recipient's phone numbers, including the country code.

Card

Sent to the card vault in step 2, except cvc, which you send in step 3.

Field	Required	Description
`name`	Yes	Cardholder name as on the card, 1 to 120 characters.
`pan`	Yes	Card number without spaces, 12 to 19 digits.
`expiry`	No	Expiry date in `MMYYYY` format.
`cvc`	No	Card security code, 3 characters.

Pay out to a new cardCopy Anchor Link

Create the payout orderCopy Anchor Link

Store the card in the vaultCopy Anchor Link

Execute the payoutCopy Anchor Link

Pay out to a saved cardCopy Anchor Link

FieldsCopy Anchor Link

OrderCopy Anchor Link

CustomerCopy Anchor Link

CardCopy Anchor Link

On this page