SIsilverflow
Create Charges

Create Charge

Create a new charge.

Optionally providing a 3DS result is supported in case 3DS was done using the 3DS Authentication endpoint or with an external party.

Diners support is <a class="experimental-tag-link" href="https://docs.silverflow.com/guides/api-lifecycle#tag/EXPERIMENTAL-Tag"><span class="tag experimental-tag">EXPERIMENTAL</span></a>.

Requires the charges:Create permission.

post/charges

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

avsboolean

Specifies whether AVS authentication should be used for the charge. When true, billingAddress is required.

Not supported for Diners.

localTransactionDateTimestring iso-8601-date-time

Date and time of the transaction in the local timezone.

transactionType'cryptocurrency' | 'high-risk-securities' | '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.

type.intent needs to be purchase.

  • cryptocurrency: A transaction involving the purchasing of cryptocurrencies. Use this for Visa only if specific type of digital asset cannot be determined.
  • high-risk-securities: A transaction involving the purchasing of high-risk securities. Only supported for Mastercard.
  • central-bank-digital-currency: A transaction involving purchase of a Central Bank Digital Currency (CBDC). Only supported for Visa.
  • stablecoin: A transaction involving purchase of stablecoins.
  • blockchain-native-coin: A transaction involving purchase of a non fiat backed blockchain coin. Only supported for Visa.
  • non-fungible-token: A transaction involving purchase of a Non Fungible Token (NFT). Only supported for Visa.

Not supported for Diners.

transactionReferencestring

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

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.

scaExemptionRequest'scp' | 'low-value' | 'tra'

This field can be used to indicate an acquirer SCA exemption request. Silverflow supports several SCA exemption request use cases, listed below:

  • Transaction risk analysis (TRA)
  • Low value payment (LVP)
  • Secure corporate payment (SCP)

Please note that these exemption requests may or may not be honored by the issuer.

allowPartialApprovalboolean

Indicates whether to allow partial approvals for this charge. If set to true the charge's and the authorization action's amount field will contain the approved amount. It is only implemented for Visa and Mastercard. It will be ignored for other card networks.

Example request

{
  "merchantAcceptorResolver": {
    "merchantAcceptorKey": "mac-1eOdAHhgstYTUhlphPFf"
  },
  "card": {
    "number": "4761070000000905",
    "cvc": "123",
    "holderName": "Joe Cardholder"
  },
  "tokenDetails": {
    "eci": "05",
    "tokenCryptogram": "112233445566778899001122334="
  },
  "amount": {
    "value": 2599,
    "currency": "EUR"
  },
  "type": {
    "cardEntry": "e-commerce"
  },
  "threeDsAuthenticationResult": {
    "authenticationValue": "kANBCCDDYJYjadADpka8KoQMqS",
    "directoryServerTransId": "5340af8a-5505-4bf6-abcd-123412341234",
    "eci": "05"
  },
  "transactionReference": "Dz3dIzE74EfH1HeTInyE",
  "billingAddress": {
    "countryCode": {
      "alpha3": "NLD"
    },
    "stateOrProvince": "NH",
    "city": "Amsterdam",
    "line1": "Langtown Road",
    "line2": "4200",
    "postalCode": "1234BC"
  },
  "riskAssessmentKey": "rak-1e1dAHhgstYTUhlphPzZ",
  "dynamicDescriptor": {
    "merchantName": "Acme Inc.",
    "merchantCity": "Amsterdam"
  },
  "foreignRetailer": {
    "amount": 1000
  },
  "subMerchant": {
    "id": "SUB123456",
    "address": {
      "countryCode": {
        "alpha3": "NLD"
      },
      "stateOrProvince": "NH",
      "city": "Amsterdam",
      "line1": "Langtown Road",
      "line2": "4200",
      "postalCode": "1234BC"
    }
  },
  "enhancedData": {
    "taxAmount": 300,
    "customerCode": "REF12345",
    "destinationAddress": {
      "countryCode": {
        "alpha3": "NLD"
      },
      "postalCode": "1234BC"
    },
    "discountAmount": 50,
    "orderDate": "2026-05-01",
    "shippingAddress": {
      "postalCode": "1234BC"
    },
    "timeOfPurchase": "1402"
  },
  "initialTransactionReferences": {
    "transactionLinkId": "qtQRrYlsSvSecPJDBzrzYA"
  }
}

Response

The created charge

keystring required

Uniquely identifies a charge.

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.
localTransactionDateTimestring iso-8601-date-time required

Date and time of the transaction in the local timezone.

transactionType'cryptocurrency' | 'high-risk-securities' | '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.

type.intent needs to be purchase.

  • cryptocurrency: A transaction involving the purchasing of cryptocurrencies. Use this for Visa only if specific type of digital asset cannot be determined.
  • high-risk-securities: A transaction involving the purchasing of high-risk securities. Only supported for Mastercard.
  • central-bank-digital-currency: A transaction involving purchase of a Central Bank Digital Currency (CBDC). Only supported for Visa.
  • stablecoin: A transaction involving purchase of stablecoins.
  • blockchain-native-coin: A transaction involving purchase of a non fiat backed blockchain coin. Only supported for Visa.
  • non-fungible-token: A transaction involving purchase of a Non Fungible Token (NFT). Only supported for Visa.

Not supported for Diners.

transactionReferencestring

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

fraudLiability'acquirer' | 'issuer' required

Which party is liable in case of fraud.

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

allowPartialApprovalboolean

Indicates whether to allow partial approvals for this charge. If set to true the charge's and the authorization action's amount field will contain the approved amount. It is only implemented for Visa and Mastercard. It will be ignored for other card networks.

versioninteger required

The version of this object

Example response

{
  "key": "chg-1e1dAHhgstYTUhlphPzZ",
  "merchantAcceptorRef": {
    "key": "mac-1eOdAHhgstYTUhlphPFf",
    "version": 1
  },
  "tokenDetails": {
    "eci": "05"
  },
  "amount": {
    "value": 2599,
    "currency": "EUR"
  },
  "cardholderBillingAmount": {
    "value": 2599,
    "currency": "EUR"
  },
  "type": {
    "cardEntry": "e-commerce"
  },
  "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"
    }
  },
  "billingAddress": {
    "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.