--- title: "Create POS Charge" method: POST path: "/charges/pos" tags: ["Create Charges"] --- # Create POS Charge `POST /charges/pos` ## Request - Base URL: `https://eu-west-1.api.silverflow.com/v1` - URL: `https://eu-west-1.api.silverflow.com/v1/charges/pos` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a new card-present charge. Requires one of the following permissions: * `charges:Create` * `charges:CreatePos` ## Headers - `Idempotency-Key` string: This key is used to deduplicate requests that are retried. For more information see the section on [Idempotency](https://docs.silverflow.com/guides/idempotency). ## Request body - ChargeCreatePos: Create a POS charge - `merchantAcceptorResolver` union, required: The resolver is used to select the appropriate merchant acceptor for creating the charge. It can accept either a `merchantAcceptorKey` or a combination of `merchantKey` and an optional `route`. If the optional property for `route` is not provided the default one generated when creating an acceptor will be used. - object: Used to select a merchant acceptor by key. - `merchantAcceptorKey` string, required: Uniquely identifies a merchant acceptor. - object: Used to select a merchant acceptor by merchant key and an optional route. - `merchantKey` string, required: Uniquely identifies a merchant. - `route` string: Route key used to uniquely reference an acceptor when used in combination with its card network and merchant key. - `card` PosCardInput, required: Card data - `number` string, password, required: Full digits of a card - `expiryMonth` integer, required: The month the card expires. January is 1 - `expiryYear` integer, required: The year the card expires including the century - `createProcessorToken` boolean: When set to `true`, Silverflow will [create a processor token](https://docs.silverflow.com/guides/card-tokenization) for the provided `card` and return a processor token key in the response field `card.processorTokenKey`. **This flag is non-blocking.** When failing to create a processor token, the authorization will take place as usual and no `card.processorTokenKey` will be returned. - `amount` RequestPosAmount, required: The amount encoded as an object with a `value` in minor units and a `currency` code. An optional `breakdown` can be provided to indicate specific sub-amounts. - `value` integer, required: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XCG' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required: An alphabetic ISO-4217 currency code. - `breakdown` RequestAmountBreakdown: A breakdown of the transaction `value`. All provided amounts must exactly add up to `value`. Providing a breakdown is only required if any other amounts besides the `baseAmount` are included. - `baseAmount` integer, required: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `cashback` integer: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `type` ChargesPosChargePosType, required: Describes the kind of POS charge the merchant wants to submit. - `intent` 'purchase' | 'reservation' | 'refund', required: The intention of the cardholder - `cardEntry` 'terminal', required: The method used to capture the card details. - `order` 'counter', required: The method used to place the order. - `terminalEntryMode` 'contactless' | 'manual-entry' | 'chip' | 'magstripe' | 'magstripe-fallback', required: This field indicates the method used for PAN entry on the terminal to initiate the transaction. - `sequence` 'subsequent': This property indicates that the cardholder has entered Online PIN, when required by the issuer for a Mastercard Single Tap transaction. - `localTransactionDateTime` string, iso-8601-date-time: Date and time of the transaction in the local timezone. - `transactionReference` string: Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction. - `track2Data` string: The information encoded on track 2 of the card magnetic stripe as defined in the ISO 7813 specification, including data element separator but excluding the beginning and ending sentinels and the LRC (Longitudinal Redundancy Check) character. This property is mandatory when the `terminalEntryMode` is `chip`, `contactless`,`magstripe` or `magstripe-fallback`. - `emvData` string: This field contains integrated circuit card (ICC) related binary data that is transmitted from the ICC to the card issuer and from the card issuer to the ICC. This field is formatted as 510 hexadecimal characters, which translates to 255 bytes. - `cardSequenceNumber` string: Distinguishes among separate cards having the same PAN. This is required if EMV tag 5F34 is present/personalized on the card chip. - `pinBlock` union: PIN block related data. - object: PIN block related data in `ISO-0` or `ISO-1` format. - `format` 'ISO-0' | 'ISO-1', required: Indicates the type of PIN block format used. - `block` string, required: Contains encrypted PIN information, formatted as an `ISO-0`/`ISO-1` block of 16 hexadecimal characters. - `zoneId` string, required: ID of the encryption zone. - `keyId` string, required: Encryption key in the specified zone to use. - object: PIN block related data in `ISO-4` format. - `format` 'ISO-4', required: Indicates the type of PIN block format used. - `block` string, required: Contains encrypted PIN information, formatted as an `ISO-4` block of 32 hexadecimal characters. - `zoneId` string, required: ID of the encryption zone. - `keyId` string, required: Encryption key in the specified zone to use. - `terminal` union, required: Details about the terminal. - object - `type` 'pos', required - `id` string, required: Terminal's ID - `attended` boolean, required: Whether the terminal is attended or not. - `capabilities` TerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. #### Restrictions If `capabilities` include `keyEntry` or `signature` then `attended` must be set to `true`. - object - `type` 'mpos', required - `id` string, required: Terminal's ID - `attended` true, required: Whether the terminal is attended or not. - `capabilities` TerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. - object - `type` 'softpos', required - `id` string, required: Terminal's ID - `attended` true, required: Whether the terminal is attended or not. - `capabilities` SoftPosTerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. - `allowPartialApproval` boolean: 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. - `subMerchant` SubMerchant: Submerchant information used in the Payment Facilitator set-up. If present, will override any subMerchant information present on the Merchant Acceptor. DISCOVER MASTERCARD VISA - `id` string: Unique ID assigned to the subMerchant. When provided, overrides `merchantAcceptor.subMerchantId`. - `address` SchemasAddressInput: A physical postal address. - `countryCode` union, required - ComponentsSchemasCountryCodeAlpha3 - `alpha3` string, required - ComponentsSchemasCountryCodeAlpha2 - `alpha2` string, required - ComponentsSchemasCountryCodeNumeric - `numeric` string, required - `stateOrProvince` string: The state (US) or province (non-US) of the address. - `city` string, required: The city of the address. - `line1` string, required: Address line 1 - `line2` string: Address line 2 - `postalCode` string, required: The postal code of the address, allowing a single separating space. - `pointOfSaleAddress` PointOfSaleAddressInput: A physical postal address. - `countryCode` union, required - ComponentsSchemasCountryCodeAlpha3 - `alpha3` string, required - ComponentsSchemasCountryCodeAlpha2 - `alpha2` string, required - ComponentsSchemasCountryCodeNumeric - `numeric` string, required - `stateOrProvince` string: The state (US) or province (non-US) of the address. - `city` string, required: The city of the address. - `line1` string, required: Address line 1 - `line2` string: Address line 2 - `postalCode` string, required: The postal code of the address, allowing a single separating space. - `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. - `clearAfter` string, 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. - `dynamicDescriptor` SchemasDynamicDescriptor: Field supports the merchant customizing the DBA name and city on a per-transaction basis, to allow the cardholder to recognize the business name and city on their card or bank statement. - `merchantName` string: Recognizable business name that will appear on the customer's card or bank statement. - `merchantCity` string: City from which the transaction originated ## Response `201` The created charge - ChargeCreatePosResponse: A POS charge - `key` string, required: Uniquely identifies a charge. - `merchantAcceptorRef` ComponentsSchemasAcceptorRef, required: Reference key and status of the acceptor - `key` string, required: Uniquely identifies a merchant acceptor. - `version` integer, required: The version of this object - `card` OutputCard, required: Card data - `maskedNumber` string, required: The card number used to create this charge, masked according to PCI standards. For card numbers with 16 or more digits, the first 8 and the last 4 digits are visible. For card numbers with 13-15 digits, the first 6 and the last 4 digits are visible. For cards numbers with less than 13 digits, the first 6 and last 2 digits are visible. - `processorTokenKey` string: The key to a card tokenized in the [Processor Tokenization](#tag/Processor-Tokenization). - `amount` object, required: The amount encoded as an object with a `value` in minor units and a `currency` code. An optional `breakdown` can be provided to indicate specific sub-amounts. - `value` integer, required: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XCG' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required: An alphabetic ISO-4217 currency code. - `breakdown` ResponseAmountBreakdown: A breakdown of the transaction `value`. All provided amounts must exactly add up to `value`. Providing a breakdown is only required if any other amounts besides the `baseAmount` are included. - `baseAmount` integer, required: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `cashback` integer: An amount in minor units. For example `$12.34` should be encoded as `1234`. - `type` ChargesPosChargePosType, required: Describes the kind of POS charge the merchant wants to submit. - `intent` 'purchase' | 'reservation' | 'refund', required: The intention of the cardholder - `cardEntry` 'terminal', required: The method used to capture the card details. - `order` 'counter', required: The method used to place the order. - `terminalEntryMode` 'contactless' | 'manual-entry' | 'chip' | 'magstripe' | 'magstripe-fallback', required: This field indicates the method used for PAN entry on the terminal to initiate the transaction. - `sequence` 'subsequent': This property indicates that the cardholder has entered Online PIN, when required by the issuer for a Mastercard Single Tap transaction. - `status` StatusPos, required: The status property provides a high-level representation of the lifecycle of a charge. For a complete history, the actions should be used. - `authentication` 'none', required: Strong Customer Authentication (SCA) status of the charge - `authorization` 'none' | 'approved' | 'approved-partial' | 'declined' | 'reversed' | 'approved-purchase-amount-only', required: Authorization status of the charge. Value 'approved-purchase-amount-only' is only returned for Mastercard charges using 'amount.breakdown.cashback'. In this case, only the 'amount.breakdown.baseAmount' was approved, but not the cashback. - `clearing` 'none' | 'manual' | 'pending' | 'completed' | 'cancelled' | 'abandoned', required: Clearing status of the charge - `localTransactionDateTime` string, iso-8601-date-time, required: Date and time of the transaction in the local timezone. - `transactionReference` string: Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction. - `newEmvData` string: This field contains integrated circuit card (ICC) related binary data that is transmitted from the card issuer to the ICC. This field is formatted as 510 hexadecimal characters, which translates to 255 bytes. If this field is present in the response message, it should be passed without modification to the ICC. - `terminalAction` 'requestPin' | 'switchInterface': Indicates if the issuer requests a PIN in Single Tap mode, or switching interface. - `authorizationIsoFields` ChargesPosPosAuthorizationIsoFields, required: Object containing the raw values from the ISO8583 response message received from the network. - `responseCode` string, required: Contents of field 39 - `responseCodeDescription` string, required: The description of the `responseCode` - `authorizationCode` string: Contents of field 38 - `networkCode` string, required: Contents of field 63, subfield 1 - `systemTraceAuditNumber` string, required: Contents of field 11 - `retrievalReferenceNumber` string, required: Contents of field 37 - `eci` '00', required - `networkSpecificFields` union, required - AmexSpecificFields: American Express-specific ISO8583 raw values - `acquirerReferenceData` string, required: Contents of field 31. - `cvcResult` string: Contents of field 44, first byte. - `avsResult` string: Contents of field 44, second byte. - DiscoverSpecificFields: Discover specific ISO8583 raw values - `network` 'discover', required: Card network providing these fields - `avsResponseCode` string: Contents field 44, usage 2, position 1. - `cidResultCode` string: Contents field 44, usage 2, position 2. - `networkReferenceId` string: Contents field 48, position 11-25. - MastercardSpecificFields: Mastercard specific ISO8583 raw values - `banknetReference` string, required: Contents of field 63, subfield 2 - `traceId` string, required: The trace ID can be used to refer to the original authorization for subsequent transactions (e.g., reversals, MITs). The value is constructed from the contents of field 63, subfield 1, field 63, subfield 2, and field 15. The value intentionally ends with two spaces. - `merchantAdviceCode` string: Contents of field 48, subelement 84 - `cvcResult` string: Contents of field 48, subelement 87 - `nameValidationResult` string: Contents of field 108, subelement 08, subfield 02. Result of Mastercard name validation check. To request name validation set `type.intent` = `account-status` and provide `card.holderName`. - `avsResponse` string: Contents of field 48, subelement 83 - `paymentAccountReference` string: Contents of field 56, subelement 1, subfield 1 - `transactionLinkId` string: Contents of field 105, subelement 1 - `digitalCommerceProgramType` string: Contents of field 48, subelement 48, subfield 2. Identifies the specific digital commerce program used. - `onBehalfServices` object[]: Contents of field 48, subelement 71. - `onBehalfService` string, required: Contents of field 48, subelement 71, subfield 1. - `onBehalfResult1` string, required: Contents of field 48, subelement 71, subfield 2. - `onBehalfResult2` string, required: Contents of field 48, subelement 71, subfield 3. - VisaSpecificFields: Visa specific ISO8583 raw values - `transactionIdentifier` string, required: Contents of field 62, subfield 2 - `cvv2ResultCode` string: Contents of field 44, subfield 10 - `avsResultCode` string: Contents of field 44, subfield 2 - `paymentAccountReference` string: Contents of field 56, dataset 1, tag 1 - `aniResults` object: Contents of field 34, dataset 4. Result of Visa Account Name Inquiry (ANI) check. To request ANI set `type.intent` = `account-status` and provide `card.holderName` - `status` string, required: Contents of field 34, dataset 4, tag C0 - `fullNameMatch` string: Contents of field 34, dataset 4, tag C4 - `firstNameMatch` string: Contents of field 34, dataset 4, tag CA - `middleNameMatch` string: Contents of field 34, dataset 4, tag C9 - `lastNameMatch` string: Contents of field 34, dataset 4, tag C8 - `vaaiScore` string: Contents of field 104, dataset 5b, tag 85 - `tokenRequestorId` string: Contents of field 123, dataset 68, tag 03. Identifies the Token Requestor Id (TRID) - `allowPartialApproval` boolean: 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. - `subMerchant` SubMerchantResponse: Submerchant information used in the Payment Facilitator set-up. This overrides any subMerchant information present on the Merchant Acceptor. - `id` string: Unique ID assigned to the subMerchant. - `address` ComponentsSchemasAddress: A physical postal address - `countryCode` SchemasCountryCode, required - `alpha3` string, required - `alpha2` string, required - `numeric` string, required - `stateOrProvince` string: The state (US) or province (non-US) of the address. - `city` string, required: The city of the address. - `line1` string, required: Address line 1 - `line2` string: Address line 2 - `postalCode` string, required: The postal code of the address, allowing a single separating space. - `pointOfSaleAddress` PointOfSaleAddress: A physical postal address - `countryCode` SchemasCountryCode, required - `alpha3` string, required - `alpha2` string, required - `numeric` string, required - `stateOrProvince` string: The state (US) or province (non-US) of the address. - `city` string, required: The city of the address. - `line1` string, required: Address line 1 - `line2` string: Address line 2 - `postalCode` string, required: The postal code of the address, allowing a single separating space. - `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. - `clearAfter` string, 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. - `dynamicDescriptor` SchemasDynamicDescriptor: Field supports the merchant customizing the DBA name and city on a per-transaction basis, to allow the cardholder to recognize the business name and city on their card or bank statement. - `merchantName` string: Recognizable business name that will appear on the customer's card or bank statement. - `merchantCity` string: City from which the transaction originated - `terminal` union, required: Details about the terminal. - object - `type` 'pos', required - `id` string, required: Terminal's ID - `attended` boolean, required: Whether the terminal is attended or not. - `capabilities` TerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. #### Restrictions If `capabilities` include `keyEntry` or `signature` then `attended` must be set to `true`. - object - `type` 'mpos', required - `id` string, required: Terminal's ID - `attended` true, required: Whether the terminal is attended or not. - `capabilities` TerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. - object - `type` 'softpos', required - `id` string, required: Terminal's ID - `attended` true, required: Whether the terminal is attended or not. - `capabilities` SoftPosTerminalCapability[], required: The capabilities of the terminal. This can be one or multiple, and if more than one is specified it means that it is capable of all of those things. - `created` string, iso-8601-date-time, required: The date and time this object was created - `lastModified` string, iso-8601-date-time: The date and time this object was last modified - `version` integer, required: The version of this object ## Other responses - `400`: Bad Request - `401`: Authentication information is missing or invalid - `403`: The authenticated client is forbidden to make the request for the resource identified. - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/silverflow/apis/silverflow-api.md) - [All operations](https://skmtc.dev/silverflow/apis/silverflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/silverflow/apis/silverflow-api/revisions/43ecbe4fd6ea?raw)