Send Card Payouts

This guide sends a payout to a card. The card is either already saved, or it arrives in the payout request.

Before you start

Credova account

Sign up or sign in to the Credova Portal.

Secret Key

Authenticates requests from your server. Never send it to the browser.

Copy your keys from the PortalTest and live keys

Send to a Saved Card

You need a saved card. Save one with Save Cards. You get a card id that starts with card_.

Process the Payout

We will use a saved card to create a new payout.

For example, given this saved card:

{
  "id": "card_AjkCFKAYiTsjghXWMzoXFPMxj",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  "cardholder_name": "John Smith",
  "last4": "4242",
  "exp_month": "12",
  "exp_year": "2025",
  "fingerprint": "CC2XvyoohnqecEq4r3FtXv6MdCx4TbaW1UUTdCCN5MNL",
  "created_at": "2024-06-30T01:02:29.212Z",
  "modified_at": "2024-06-30T01:02:29.212Z"
}

Create a Payout

We need to make a call to Create Payout endpoint:

Create a Payout

curl 'https://api.publicsquare.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": "card_AjkCFKAYiTsjghXWMzoXFPMxj"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  }
}'

The amount is provided in cents. 1000 is the equivalent of $10.00

The IDEMPOTENCY-KEY header can be passed to protect against duplicate payouts being processed.

Create with Existing Customer

If you created a customer, then you can pass its ID as customer.id when processing the payout:

Create a Payout with Customer

curl 'https://api.publicsquare.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": "card_AjkCFKAYiTsjghXWMzoXFPMxj"
  },
  "customer": {
    "id": "cus_7Ay5mcUXAxwrN6wQEQUVEHBCJ"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  }
}'

Create with Customer's Payment Method

If you attached the card to a customer, then you can omit the customer section when processing the payout:

Create a Payout with Payment Method

curl 'https://api.publicsquare.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": "card_AjkCFKAYiTsjghXWMzoXFPMxj"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  }
}'

Create with Payment Method's Billing Details

If you supplied the billing_details or updated the card, then you can omit the billing_details section when processing the payout:

Create a Payout with Payment Method

curl 'https://api.publicsquare.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": "card_AjkCFKAYiTsjghXWMzoXFPMxj"
  }
}'

Payout Response

Given the card payout examples, you should see a payout result similar to:

{
  "id": "pyt_24NFPd3jSZFTxiaH9UwjuqNdP",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  "status": "succeeded",
  "transaction_id": "trx_6QgmXzQzk3S5K5EsR3DfEiMRj",
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": {
      "id": "card_AjkCFKAYiTsjghXWMzoXFPMxj",
      "cardholder_name": "John Smith",
      "last4": "4242",
      "exp_month": "12",
      "exp_year": "2025",
      "brand": "visa",
      "avs_code": "Y",
      "cvv2_reply": "M",
      "fingerprint": "CC2XvyoohnqecEq4r3FtXv6MdCx4TbaW1UUTdCCN5MNL"
    }
  },
  "customer": {
    "id": "cus_7Ay5mcUXAxwrN6wQEQUVEHBCJ",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com",
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  },
  "transaction": {
    "id": "trx_6QgmXzQzk3S5K5EsR3DfEiMRj",
    "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
    "environment": "test",
    "status": "succeeded",
    "amount": -1000,
    "fee_amount": 0,
    "net_amount": -1000,
    "currency": "USD",
    "type_id": "pyt_24NFPd3jSZFTxiaH9UwjuqNdP",
    "type": "payout",
    "processor": "nuvei",
    "processor_id": "7110000000010554769",
    "created_at": "2024-06-30T01:02:29.212Z",
    "modified_at": "2024-06-30T01:02:29.212Z"
  },
  "created_at": "2024-06-30T01:02:29.212Z",
  "modified_at": "2024-06-30T01:02:29.212Z"
}

Send with Card Details

Your servers receive and send cardholder data in this flow, so your organization must be PCI certified. If you are unsure, please contact support. To keep card data out of your servers, save the card with Credova Elements and send to a saved card.

Send the card details in the same request that creates the payout. You do not need to save the card first. The API saves the card to the customer and returns its id for later payouts.

A restricted key needs the payment-method:write or payment-method:capture permission, in addition to payout:write.

To create a payment with card details, see Accept Card Payments.

Send Card Details

Send the request to the secure hostname for the mode of your API key. The secure hostname turns the card into a token before the request reaches the Credova API.

Mode	Hostname	API key
Live	https://secure.payments.credova.com	Live Secret Key
Test	https://secure.payments.sbx.credova.com	Test mode Secret Key

Use the hostname that matches the mode of your API key. Each hostname saves the card for its own mode, so a key from the other mode makes the request fail.

Put the card in payment_method.card_details:

Field	Required	Description
cardholder_name	Yes	Name on the card.
number	Yes	Card number, digits only.
expiration_month	Yes	Expiration month, from 1 to 12.
expiration_year	Yes	Four-digit expiration year.
cvc	No	Card security code. A card sent without a CVC can decline more often.

The request also needs customer (or customer.id) and billing_details. The rest of the body is the same as a request to https://api.publicsquare.com.

Process a Payout

A payout with card_details does not need device_information.

Create a Payout

Create a Payout with Card Details

curl 'https://secure.payments.credova.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card_details": {
      "cardholder_name": "John Smith",
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2030,
      "cvc": "123"
    }
  },
  "customer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  }
}'

The amount is provided in cents. 1000 is the equivalent of $10.00

To test, send the same request to https://secure.payments.sbx.credova.com with your test mode Secret Key and a test card.

Create with Existing Customer

If you created a customer, pass its ID as customer.id:

Create a Payout with Customer

curl 'https://secure.payments.credova.com/payouts' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'IDEMPOTENCY-KEY: 09ec2c87-7fb8-44ca-bb18-5c71a76974da' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card_details": {
      "cardholder_name": "John Smith",
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2030,
      "cvc": "123"
    }
  },
  "customer": {
    "id": "cus_7Ay5mcUXAxwrN6wQEQUVEHBCJ"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  }
}'

Payout Response

The response is the same as for a payout with a saved card. payment_method.card describes the card that the request saved:

Payout Response

{
  "id": "pyt_24NFPd3jSZFTxiaH9UwjuqNdP",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  "status": "succeeded",
  "transaction_id": "trx_6QgmXzQzk3S5K5EsR3DfEiMRj",
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "card": {
      "id": "card_AjkCFKAYiTsjghXWMzoXFPMxj",
      "cardholder_name": "John Smith",
      "last4": "4242",
      "bin": "424242",
      "exp_month": "12",
      "exp_year": "2030",
      "brand": "visa",
      "avs_code": "Y",
      "cvv2_reply": "M",
      "fingerprint": "CC2XvyoohnqecEq4r3FtXv6MdCx4TbaW1UUTdCCN5MNL"
    }
  },
  "customer": {
    "id": "cus_7Ay5mcUXAxwrN6wQEQUVEHBCJ",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com"
  },
  "billing_details": {
    "address_line_1": "111 Test St.",
    "city": "Des Moines",
    "state": "IA",
    "postal_code": "51111",
    "country": "US"
  },
  "transaction": {
    "id": "trx_6QgmXzQzk3S5K5EsR3DfEiMRj",
    "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
    "environment": "test",
    "status": "succeeded",
    "amount": -1000,
    "fee_amount": 0,
    "net_amount": -1000,
    "currency": "USD",
    "type_id": "pyt_24NFPd3jSZFTxiaH9UwjuqNdP",
    "type": "payout",
    "processor": "nuvei",
    "processor_id": "7110000000010554769",
    "created_at": "2024-06-30T01:02:29.212Z",
    "modified_at": "2024-06-30T01:02:29.212Z"
  },
  "created_at": "2024-06-30T01:02:29.212Z",
  "modified_at": "2024-06-30T01:02:29.212Z"
}

Store payment_method.card.id. For the next payout with this card, send "payment_method": { "card": "<card id>" } to https://api.publicsquare.com/payouts, as in Send Card Payouts. A saved card is a token, so this request does not need the secure hostname.

Retries

Send an IDEMPOTENCY-KEY header with every request. If a request times out, send it again with the same key and the same card. The API returns the result of the first request and does not save the card again.

If you send the same key with a different card, the API returns 400 with an error on payment_method.card_details. Without a key, every retry saves the card again.

Errors

The secure hostname checks the card before the request reaches the Credova API:

Status	Cause
400	A card field is missing or not valid. Each key in errors starts with payment_method.card_details., for example payment_method.card_details.number.
400	The card could not be turned into a token. The detail field gives the reason.
404	The request is not a POST to /payments or /payouts.
502	The secure hostname could not reach the card vault. Send the request again with the same IDEMPOTENCY-KEY.

All other responses come from the Credova API. See Errors.

Conclusion

Now that we have sent a payout to a card, we may need to cancel it or view information about it. Follow these guides to learn more:

• Cancel Payouts
• Search and View Transactions