SIsilverflow
Create Charges

Create Payout Charge

Create a new payout charge. For more information on use-cases, see here.

NOTE: This endpoint requires configuration on a per client basis and may be subject to additional approvals and implementation with the card schemes. Contact your Silverflow representative before integrating with this endpoint.

Currently only supported for Visa and Mastercard.

Requires the charges:CreatePayout or charges:Create permission.

post/charges/payout

Request

Headers

Idempotency-Keystring

This key is used to deduplicate requests that are retried. For more information see the section on Idempotency.

Example:28gKCluIEKp8jVboUyr2

Request body

localTransactionDateTimestring iso-8601-date-time

Date and time of the transaction in the local timezone.

transactionReferencestring

Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction.

fundingSource'credit' | 'debit' | 'prepaid' | 'deposit-account' | 'mobile-money-account' | 'cash' | 'other'

The source of the funds for the payout. mobile-money-account is specific to Mastercard transactions. The rest are common to both networks.

Required for all Mastercard Payouts.

transactionType'tax-refund' | 'cryptocurrency' | 'central-bank-digital-currency' | 'stablecoin' | 'blockchain-native-coin' | 'non-fungible-token'

In case of a special transaction type, this allows you to specify which one.

  • tax-refund: A transaction involving a tax rebate. Only allowed for payoutType of general-funds-disbursement. Required for USA cardholders. <span class="tag network-tag visa-tag">VISA</span>
  • cryptocurrency: A transaction involving the purchasing of cryptocurrencies. Use this for Visa only if specific type of digital asset cannot be determined. Only allowed for Mastercard when payoutType is account-to-account. <span class="tag network-tag visa-tag">VISA</span><span class="tag network-tag mastercard-tag">MASTERCARD</span>
  • central-bank-digital-currency: A transaction involving purchase of a Central Bank Digital Currency (CBDC). <span class="tag network-tag visa-tag">VISA</span>
  • stablecoin: A transaction involving purchase of stablecoins. <span class="tag network-tag visa-tag">VISA</span>
  • blockchain-native-coin: A transaction involving purchase of a non fiat backed blockchain coin. <span class="tag network-tag visa-tag">VISA</span>
  • non-fungible-token: A transaction involving purchase of a Non Fungible Token (NFT). <span class="tag network-tag visa-tag">VISA</span>
purposeOfPaymentstring

A code that describes the purpose of payment to classify and report the nature and purpose of the transaction. Refer to Visa documentation for country specific requirements for this field.

clearingMode'auto' | 'manual'

The clearing method for the charge.

  • auto: The charge is cleared automatically as soon as possible. To delay clearing, provide a clearAfter timestamp.
  • manual: The charge must be manually cleared later.
clearAfterstring iso-8601-date-time

If provided, clearing will not occur before this point in time. If no timezone is included, it is assumed to be UTC. The value may be at most 6 months in the future from when the charge was created.

riskAssessmentKeystring

Key that was returned by the transaction risk assessment.

Example request

{
  "merchantAcceptorResolver": {
    "merchantAcceptorKey": "mac-1eOdAHhgstYTUhlphPFf"
  },
  "card": {
    "number": "4761070000000905",
    "cvc": "123",
    "holderName": "Joe Cardholder"
  },
  "amount": {
    "value": 2599,
    "currency": "EUR"
  },
  "initialTransactionReferences": {
    "initialTransactionIdentifier": "303219322378732"
  },
  "threeDsAuthenticationResult": {
    "authenticationValue": "kANBCCDDYJYjadADpka8KoQMqS",
    "directoryServerTransId": "5340af8a-5505-4bf6-abcd-123412341234",
    "eci": "05"
  },
  "transactionReference": "Dz3dIzE74EfH1HeTInyE",
  "sender": {
    "organizationName": "Name",
    "firstName": "Name",
    "middleName": "Name",
    "lastName": "Name",
    "accountNumber": "5286940020000007",
    "address": {
      "countryCode": {
        "alpha3": "NLD"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  },
  "receiver": {
    "organizationName": "Name",
    "firstName": "Name",
    "middleName": "Name",
    "lastName": "Name",
    "accountNumber": "5286940020000007",
    "address": {
      "countryCode": {
        "alpha3": "NLD"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  },
  "dynamicDescriptor": {
    "merchantName": "Acme Inc.",
    "merchantCity": "Amsterdam"
  },
  "riskAssessmentKey": "rak-1e1dAHhgstYTUhlphPzZ",
  "foreignRetailer": {
    "amount": 1000
  },
  "subMerchant": {
    "id": "SUB123456",
    "address": {
      "countryCode": {
        "alpha3": "NLD"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  }
}

Response

The created charge

keystring required

Uniquely identifies a charge.

clearingMode'none' | 'auto' | 'manual' required

The clearing mode of the charge.

localTransactionDateTimestring iso-8601-date-time required

Date and time of the transaction in the local timezone.

transactionType'tax-refund' | 'cryptocurrency' | 'central-bank-digital-currency' | 'stablecoin' | 'blockchain-native-coin' | 'non-fungible-token'

In case of a special transaction type, this allows you to specify which one.

  • tax-refund: A transaction involving a tax rebate. Only allowed for payoutType of general-funds-disbursement. Required for USA cardholders. <span class="tag network-tag visa-tag">VISA</span>
  • cryptocurrency: A transaction involving the purchasing of cryptocurrencies. Use this for Visa only if specific type of digital asset cannot be determined. Only allowed for Mastercard when payoutType is account-to-account. <span class="tag network-tag visa-tag">VISA</span><span class="tag network-tag mastercard-tag">MASTERCARD</span>
  • central-bank-digital-currency: A transaction involving purchase of a Central Bank Digital Currency (CBDC). <span class="tag network-tag visa-tag">VISA</span>
  • stablecoin: A transaction involving purchase of stablecoins. <span class="tag network-tag visa-tag">VISA</span>
  • blockchain-native-coin: A transaction involving purchase of a non fiat backed blockchain coin. <span class="tag network-tag visa-tag">VISA</span>
  • non-fungible-token: A transaction involving purchase of a Non Fungible Token (NFT). <span class="tag network-tag visa-tag">VISA</span>
transactionReferencestring

Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction.

fundingSource'credit' | 'debit' | 'prepaid' | 'deposit-account' | 'mobile-money-account' | 'cash' | 'other'

The source of the funds for the payout. mobile-money-account is specific to Mastercard transactions. The rest are common to both networks.

Required for all Mastercard Payouts.

purposeOfPaymentstring

A code that describes the purpose of payment to classify and report the nature and purpose of the transaction. Refer to Visa documentation for country specific requirements for this field.

clearAfterstring iso-8601-date-time

If provided, clearing will not occur before this point in time. If no timezone is included, it is assumed to be UTC. The value may be at most 6 months in the future from when the charge was created.

createdstring iso-8601-date-time required

The date and time this object was created

lastModifiedstring iso-8601-date-time

The date and time this object was last modified

versioninteger required

The version of this object

Example response

{
  "key": "chg-1e1dAHhgstYTUhlphPzZ",
  "merchantAcceptorRef": {
    "key": "mac-1eOdAHhgstYTUhlphPFf",
    "version": 1
  },
  "amount": {
    "value": 2599,
    "currency": "EUR"
  },
  "status": {
    "authentication": "authenticated",
    "authorization": "approved",
    "clearing": "pending"
  },
  "authentication": {
    "sca": {
      "result": {
        "directoryServerTransId": "5340af8a-5505-4bf6-abcd-123412341234"
      }
    }
  },
  "transactionReference": "Dz3dIzE74EfH1HeTInyE",
  "authorizationIsoFields": {
    "responseCode": "00",
    "responseCodeDescription": "Approved",
    "authorizationCode": "4A4316",
    "systemTraceAuditNumber": "123456",
    "retrievalReferenceNumber": "131608123456",
    "networkSpecificFields": {
      "cvcResult": "Y",
      "avsResult": "Y"
    }
  },
  "sender": {
    "organizationName": "Name",
    "firstName": "Name",
    "middleName": "Name",
    "lastName": "Name",
    "accountNumber": "************0007",
    "address": {
      "countryCode": {
        "alpha3": "NLD",
        "alpha2": "NL",
        "numeric": "528"
      }
    }
  },
  "receiver": {
    "organizationName": "Name",
    "firstName": "Name",
    "middleName": "Name",
    "lastName": "Name",
    "accountNumber": "************0007",
    "address": {
      "countryCode": {
        "alpha3": "NLD",
        "alpha2": "NL",
        "numeric": "528"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  },
  "dynamicDescriptor": {
    "merchantName": "Acme Inc.",
    "merchantCity": "Amsterdam"
  },
  "foreignRetailer": {
    "amount": 1000
  },
  "subMerchant": {
    "id": "SUB123456",
    "address": {
      "countryCode": {
        "alpha3": "NLD",
        "alpha2": "NL",
        "numeric": "528"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  },
  "version": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.