--- title: "Process a register: registers a customer's payment instrument for future use (Debit or Preauthorize)" method: POST path: "/transaction/{apiKey}/register" tags: ["transaction"] --- # Process a register: registers a customer's payment instrument for future use (Debit or Preauthorize) `POST /transaction/{apiKey}/register` ## Request - Base URL: `https://gateway.tillpayments.com/api/v3` - URL: `https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Path parameters - `apiKey` string, required ## Request body - Register - `merchantTransactionId` string, required - `additionalId1` string - `additionalId2` string - `extraData` ExtraData - `pspPassthroughData` PspPassthroughData - `merchantMetaData` string - `successUrl` string - `cancelUrl` string - `errorUrl` string - `callbackUrl` string - `transactionToken` string - `description` string - `transactionIndicator` 'SINGLE' | 'INITIAL' | 'RECURRING' | 'FIRST-CARDONFILE' | 'CARDONFILE' | 'CARDONFILE-MERCHANT-INITIATED' | 'MOTO' - `customer` Customer - `identification` string - `firstName` string - `lastName` string - `birthDate` string - `gender` 'M' | 'F' - `billingAddress1` string - `billingAddress2` string - `billingCity` string - `billingPostcode` string - `billingState` string - `billingCountry` string - `billingPhone` string - `shippingFirstName` string - `shippingLastName` string - `shippingCompany` string - `shippingAddress1` string - `shippingAddress2` string - `shippingCity` string - `shippingPostcode` string - `shippingState` string - `shippingCountry` string - `shippingPhone` string - `company` string - `email` string - `emailVerified` boolean - `ipAddress` string - `nationalId` string - `extraData` ExtraData - `paymentData` union - IbanData - `ibanData` object - `iban` string - `bic` string - `mandateId` string - `mandateDate` string - WalletData - `walletData` object - `walletReferenceId` string - `walletOwner` string - `walletType` string - `schedule` Schedule - `amount` string, required - `currency` string, required - `periodLength` integer, required - `periodUnit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required - `startDateTime` string - `merchantMetaData` string - `callbackUrl` string - `customerProfileData` CustomerProfileData - `profileGuid` string - `customerIdentification` string - `paymentToken` string - `markAsPreferred` boolean - `threeDSecureData` ThreeDSecureData - `3dsecure` 'OFF' | 'OPTIONAL' | 'MANDATORY' - `schemeId` 'CB' | 'Eftpos' - `channel` '01' | '02' | '03' - `authenticationIndicator` '01' | '02' | '03' | '04' | '05' | '06' - `cardholderAuthenticationMethod` '01' | '02' | '03' | '04' | '05' | '06' - `cardholderAuthenticationDateTime` string - `cardHolderAuthenticationData` string - `challengeIndicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' - `priorReference` string - `priorAuthenticationMethod` '01' | '02' | '03' | '04' - `priorAuthenticationDateTime` string - `priorAuthenticationData` string - `cardholderAccountType` '01' | '02' | '03' | '04' - `cardholderAccountAgeIndicator` '01' | '02' | '03' | '04' | '05' - `cardholderAccountDate` string - `cardholderAccountChangeIndicator` '01' | '02' | '03' | '04' - `cardholderAccountLastChange` string - `cardholderAccountPasswordChangeIndicator` '01' | '02' | '03' | '04' | '05' - `cardholderAccountLastPasswordChange` string - `shippingAddressUsageIndicator` '01' | '02' | '03' | '04' - `shippingAddressFirstUsage` string - `transactionActivityDay` number - `transactionActivityYear` number - `addCardAttemptsDay` number - `purchaseCountSixMonths` number - `suspiciousAccountActivityIndicator` '01' | '02' - `shippingNameEqualIndicator` '01' | '02' - `paymentAccountAgeIndicator` '01' | '02' | '03' | '04' | '05' - `paymentAccountAgeDate` string - `billingAddressLine3` string - `shippingAddressLine3` string - `billingShippingAddressMatch` 'Y' | 'N' - `homePhoneCountryPrefix` string - `homePhoneNumber` string - `mobilePhoneCountryPrefix` string - `mobilePhoneNumber` string - `workPhoneCountryPrefix` string - `workPhoneNumber` string - `purchaseInstalData` number - `shipIndicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' - `deliveryTimeframe` '01' | '02' | '03' | '04' - `deliveryEmailAddress` string - `reorderItemsIndicator` '01' | '02' - `preOrderPurchaseIndicator` '01' | '02' - `preOrderDate` string - `giftCardAmount` number - `giftCardCurrency` string - `giftCardCount` number - `purchaseDate` string - `recurringExpiry` string - `recurringFrequency` number - `transType` '01' | '03' | '10' | '11' | '28' - `exemptionIndicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' - `threeRIIndicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '12' - `browserChallengeWindowSize` '01' | '02' | '03' | '04' | '05' - `browserAcceptHeader` string - `browserIpAddress` string - `browserJavaEnabled` boolean - `browserLanguage` string - `browserColorDepth` union - integer - '1' | '4' | '8' | '15' | '16' | '24' | '30' | '32' | '48' - `browserScreenHeight` union - number - string - `browserScreenWidth` union - number - string - `browserTimezone` union - integer - string - `browserUserAgent` string - `browserPlatform` string - `sdkInterface` '01' | '02' | '03' - `sdkUiType` string - `sdkAppID` string - `sdkEncData` string - `sdkEphemPubKey` string - `sdkMaxTimeout` number - `sdkReferenceNumber` string - `sdkTransID` string - `payByLink` PayByLink - `sendByEmail` boolean - `expirationInMinute` integer - `language` string - `l2l3Data` L2L3Data - `taxAmount` string - `vatRegistrationNumber` string - `nationalTaxIncluded` string - `discountAmount` string - `commodityCode` string - `freightAmount` string - `freightTaxAmount` string - `dutyAmount` string - `taxDetails` object[] - `type` string - `amount` string - `rate` string - `code` string - `taxId` string - `applied` string - `exemptionCode` string - `referenceUuid` string: UUID of a previous register transaction on the same merchant. Used by the register-with-expiry-update flow to point at the existing token whose expiry date should be patched. When set together with extraData.expiryMonthUpdate / expiryYearUpdate, the request becomes a card-data-less expiry refresh — no PAN/CVV is required. ## Response `200` Transaction response - TransactionResponse - `success` boolean - `uuid` string - `purchaseId` string - `returnType` 'FINISHED' | 'REDIRECT' | 'HTML' | 'PENDING' | 'ERROR' | 'PENDING_DCC' - `redirectType` 'iframe' | 'fullpage' | '3ds' - `redirectUrl` string - `redirectQRCode` string: DataUrl - `htmlContent` string - `paymentDescriptor` string - `paymentMethod` string - `adapterMerchantTransactionId` string: Adapter/PSP-side merchant transaction identifier recorded for transaction matching and reconciliation. Omitted when unavailable. - `amount` string - `surchargeAmount` string - `gstAmount` string - `totalAmount` string - `returnData` union - ReturnCardData - `_TYPE` 'cardData' - `type` string - `firstName` string - `lastName` string - `country` string - `cardHolder` string - `expiryMonth` string - `expiryYear` string - `binDigits` string - `firstSixDigits` string - `lastFourDigits` string - `fingerprint` string - `binBrand` string - `binBank` string - `binType` string - `binLevel` string - `binCountry` string - `binSegment` 'Consumer' | 'Business' | 'Commercial' | 'Government' | 'Unknown' - `binRawData` object - `type` string - `data` object - `threeDSecure` string - `eci` string - `merchantAdviceCode` string - `parsedMerchantAdviceCode` string - `schemeTransactionIdentifier` string - `schemeLifecycleIdentifier` string - `referenceSchemeLifecycleIdentifier` string - `cardUpdateStatus` 'updated' | 'contact' | 'new-expiry' | 'closed': Account updater transaction status - `cardUpdatedAt` string, date: Last run of the batch - `cardUpdatePausedUntil` string, date: Updates paused until this date - ReturnPhoneData - `_TYPE` 'phoneData' - `phoneNumber` string - `country` string - `operator` string - ReturnIbanData - `_TYPE` 'ibanData' - `accountOwner` string - `iban` string - `bic` string - `mandateId` string - `mandateDate` string - `bankName` string - `bankBranchName` string - `country` string - ReturnWalletData - `_TYPE` 'walletData' - `walletReferenceId` string - `walletOwner` string - `walletType` string - `scheduleData` ScheduleData - `scheduleId` string - `scheduleStatus` 'ACTIVE' | 'PAUSED' | 'CANCELLED' | 'ERROR' | 'CREATE-PENDING' - `scheduledAt` string - `merchantMetaData` string - `customerProfileData` CustomerProfileData - `profileGuid` string - `customerIdentification` string - `paymentToken` string - `markAsPreferred` boolean - `riskCheckData` object - `riskCheckResult` 'APPROVED' | 'DECLINED' | 'REVIEW' - `riskScore` number - `threeDSecureRequired` boolean - `errors` object[] - `errorMessage` string - `errorCode` integer - `adapterMessage` string - `adapterCode` string - `adapterMessage` string - `adapterCode` string - `extraData` ExtraData - `dccData` object - `uuid` string - `originalAmount` string - `originalCurrency` string - `convertedAmount` string - `convertedCurrency` string - `conversionRate` number - `disclaimer` string ## Changes - **2026-11-07** `42c40d316a83`: 1 warning, 11 info - changed the pattern of the request property `threeDSecureData/browserTimezone/anyOf[subschema #2]/` from `^[\-]?\d+$` to `^[\-\+]?\d{1,4}$` - added the new optional request property `customerProfileData/paymentToken` - added the new optional request property `referenceUuid` - added the new `Eftpos` enum value to the request property `threeDSecureData/schemeId` - …8 more - **2025-04-27** `5d765c6bfe90`: 3 info - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/binRawData` to the response with the `200` status - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/binSegment` to the response with the `200` status - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/cardUpdatePausedUntil` to the response with the `200` status - **2024-07-22** `65196339abf0`: 6 info - added the new optional request property `l2l3Data/dutyAmount` - added the new optional request property `l2l3Data/freightTaxAmount` - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/cardUpdateStatus` to the response with the `200` status - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/cardUpdatedAt` to the response with the `200` status - …2 more [Operation history](https://skmtc.dev/tillpayments/apis/till-payments-gateway/changes/transaction/:apiKey/register/post.md) --- [API](https://skmtc.dev/tillpayments/apis/till-payments-gateway.md) - [All operations](https://skmtc.dev/tillpayments/apis/till-payments-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/tillpayments/apis/till-payments-gateway/revisions/42c40d316a83?raw)