Skip to content
OneOne Docs

payments reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

POST /v1/payments/apple/sync

Section titled “POST /v1/payments/apple/sync”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ customerId: string;
  transactions: { signedTransactionInfo: string;
  transactionId?: string | undefined;
  originalTransactionId?: string | undefined;
  productId?: string | undefined;
  purchaseDate?: number | undefined;
  expiresDate?: number | null | undefined;
  quantity?: number | undefined;
  type?: "purchase" | "restore" | "renewal" | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  environment?: string | null | undefined;
  }[];
  placementId?: string | undefined;
  campaignId?: string | undefined;
  campaignAudienceId?: string | undefined;
  campaignVariantId?: string | undefined;
  campaignAssignmentId?: string | undefined;
  paywallId?: string | undefined;
  paywallProductId?: string | undefined;
  }
"account" | "app_store"

Validation schemas: appleSyncRequestSchema in the downloadable schema registry.

Response

Section titled “Response”
JSON response shape 
{ error: string;
  message: string;
  }
JSON response shape 
{ customerId: string;
  processed: number;
  skipped: number;
  mergedCustomers: number;
  customerLinkConflicts: number;
  errors: AppleSyncError[];
  error: string;
  message: string;
  requestId: string | undefined;
  operationId: string | undefined;
  retryable: true;
  success: false;
  }
JSON response shape 
{ customerId: string;
  processed: number;
  skipped: number;
  mergedCustomers: number;
  customerLinkConflicts: number;
  errors: AppleSyncError[];
  success: boolean;
  requestId: string | undefined;
  operationId: string | undefined;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: syncAppleTransactions.

POST /v1/payments/apple/app-account-token

Section titled “POST /v1/payments/apple/app-account-token”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

No JSON body is required.

Response

Section titled “Response”
JSON response shape 
{ error: string;
  message: string;
  }
JSON response shape 
{ appAccountToken: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getAppleAppAccountToken.

GET /v1/payments/apple/restore-catalog

Section titled “GET /v1/payments/apple/restore-catalog”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Use the path parameters above and any query options described below.

Response

Section titled “Response”
JSON response shape 
{ productIds: string[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getAppleRestoreCatalog.

POST /v1/payments/apple/reconcile

Section titled “POST /v1/payments/apple/reconcile”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ transactions: { signedTransactionInfo: string;
  transactionId?: string | undefined;
  originalTransactionId?: string | undefined;
  productId?: string | undefined;
  purchaseDate?: number | undefined;
  expiresDate?: number | null | undefined;
  quantity?: number | undefined;
  type?: "purchase" | "restore" | "renewal" | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  environment?: string | null | undefined;
  }[];
  placementId?: string | undefined;
  campaignId?: string | undefined;
  campaignAudienceId?: string | undefined;
  campaignVariantId?: string | undefined;
  campaignAssignmentId?: string | undefined;
  paywallId?: string | undefined;
  paywallProductId?: string | undefined;
  }
"account" | "app_store"

Response

Section titled “Response”
JSON response shape 
{ error: string;
  message: string;
  }
JSON response shape 
{ requestId: string | undefined;
  operationId: string | undefined;
  customerId: string;
  processed: number;
  skipped: number;
  mergedCustomers: number;
  customerLinkConflicts: number;
  errors: AppleSyncError[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: reconcileAppleTransactions.

POST /v1/payments/apple/access

Section titled “POST /v1/payments/apple/access”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ transactionJws: string[];
  deviceVerificationId?: string | undefined;
  appTransactionJws?: string | undefined;
  appReceipt?: string | undefined;
  receiptVendorIdentifier?: string | undefined;
  renewalInfoJws?: string[] | undefined;
  }
{ deviceVerificationId: string;
  providerEnvironment: "Production" | "Sandbox";
  transactionJws: string[];
  renewalInfoJws: string[];
  transactionsComplete: boolean;
  appTransactionJws?: string | undefined;
  appReceipt?: string | undefined;
  receiptVendorIdentifier?: string | undefined;
  }
{ observedAt: string;
  stage: string;
  nativeDomain: string;
  nativeCode: number;
  storeKitCase?: string | null | undefined;
  underlying?: { domain: string;
  code: number;
  }[] | undefined;
  }[]
{ version: 1;
  id: string;
  requestId: string;
  operationId: string | null;
  route: "access" | "evidence";
  receivedAt: string;
  finishedAt: string;
  verifiedAt: string | null;
  policy: "account" | "app_store" | null;
  configurationRevision: string | null;
  providerEnvironment: "Production" | "Sandbox" | null;
  outcome: "failed" | "partial" | "verified";
  completeness: "failed" | "complete" | "partial" | "submitted_evidence";
  acquisitionVerified: boolean | null;
  transactionCounts: { submitted: number;
  verified: number | null;
  active: number | null;
  inactive: number | null;
  unverified: number | null;
  unmapped: number | null;
  } | null;
  entitlements: { identifier: string;
  expiresAt: number | null;
  source: "manual" | "apple";
  }[];
  entitlementsTruncated: boolean;
  responseExpiresAt: number | null;
  accessContextExpiresAt: number | null;
  stage: "completed" | "acquisition" | "configuration" | "transactions" | "mapping" | "purchaser_link" | "context_signing" | "contract_validation";
  failure: { code: "invalid_contract" | "verification_rejected" | "service_error";
  httpStatus: number;
  retryable: boolean;
  } | null;
  appVersion: string | null;
  sdkVersion: string | null;
  deviceModel: string | null;
  osVersion: string | null;
  versionProvenance: "unknown" | "request_headers";
  attemptId?: string | null | undefined;
  evidenceIssues?: { source: "renewal" | "acquisition" | "transaction" | "mapping";
  reason: "verification_failed" | "claims_invalid" | "device_mismatch" | "environment_mismatch" | "unmatched_renewal" | "catalog_mapping_failed";
  index?: number | undefined;
  }[] | undefined;
  }

Response

Section titled “Response”
JSON response shape 
{ entitlements: EntitlementsMap;
  manualEntitlements: EntitlementsMap;
  accessContext: string;
  expiresAt: number;
  appTransactionId: string;
  providerEnvironment: string;
  }
JSON response shape 
{ version: 2;
  entitlements: EntitlementsMap;
  acquisitionEntitlements: EntitlementsMap;
  manualEntitlements: EntitlementsMap;
  transactionResults: { index: number;
  status: typeof APPLE_EVIDENCE_RESULTS[number];
  entitlementIdentifiers: string[];
  expiresAt?: number | null;
  }[];
  acquisitionVerified: boolean;
  complete: boolean;
  accessContext: string | undefined;
  expiresAt: number;
  verifiedAt: number;
  appTransactionId: string | undefined;
  providerEnvironment: "Production" | "Sandbox";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: verifyApplePaidAccess.

POST /v1/payments/apple/access/evidence

Section titled “POST /v1/payments/apple/access/evidence”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ transactionJws: string[];
  deviceVerificationId?: string | undefined;
  appTransactionJws?: string | undefined;
  appReceipt?: string | undefined;
  receiptVendorIdentifier?: string | undefined;
  renewalInfoJws?: string[] | undefined;
  }
{ deviceVerificationId: string;
  providerEnvironment: "Production" | "Sandbox";
  transactionJws: string[];
  renewalInfoJws: string[];
  transactionsComplete: boolean;
  appTransactionJws?: string | undefined;
  appReceipt?: string | undefined;
  receiptVendorIdentifier?: string | undefined;
  }
{ observedAt: string;
  stage: string;
  nativeDomain: string;
  nativeCode: number;
  storeKitCase?: string | null | undefined;
  underlying?: { domain: string;
  code: number;
  }[] | undefined;
  }[]
{ version: 1;
  id: string;
  requestId: string;
  operationId: string | null;
  route: "access" | "evidence";
  receivedAt: string;
  finishedAt: string;
  verifiedAt: string | null;
  policy: "account" | "app_store" | null;
  configurationRevision: string | null;
  providerEnvironment: "Production" | "Sandbox" | null;
  outcome: "failed" | "partial" | "verified";
  completeness: "failed" | "complete" | "partial" | "submitted_evidence";
  acquisitionVerified: boolean | null;
  transactionCounts: { submitted: number;
  verified: number | null;
  active: number | null;
  inactive: number | null;
  unverified: number | null;
  unmapped: number | null;
  } | null;
  entitlements: { identifier: string;
  expiresAt: number | null;
  source: "manual" | "apple";
  }[];
  entitlementsTruncated: boolean;
  responseExpiresAt: number | null;
  accessContextExpiresAt: number | null;
  stage: "completed" | "acquisition" | "configuration" | "transactions" | "mapping" | "purchaser_link" | "context_signing" | "contract_validation";
  failure: { code: "invalid_contract" | "verification_rejected" | "service_error";
  httpStatus: number;
  retryable: boolean;
  } | null;
  appVersion: string | null;
  sdkVersion: string | null;
  deviceModel: string | null;
  osVersion: string | null;
  versionProvenance: "unknown" | "request_headers";
  attemptId?: string | null | undefined;
  evidenceIssues?: { source: "renewal" | "acquisition" | "transaction" | "mapping";
  reason: "verification_failed" | "claims_invalid" | "device_mismatch" | "environment_mismatch" | "unmatched_renewal" | "catalog_mapping_failed";
  index?: number | undefined;
  }[] | undefined;
  }

Response

Section titled “Response”
JSON response shape 
{ entitlements: EntitlementsMap;
  manualEntitlements: EntitlementsMap;
  accessContext: string;
  expiresAt: number;
  appTransactionId: string;
  providerEnvironment: string;
  }
JSON response shape 
{ version: 2;
  entitlements: EntitlementsMap;
  acquisitionEntitlements: EntitlementsMap;
  manualEntitlements: EntitlementsMap;
  transactionResults: { index: number;
  status: typeof APPLE_EVIDENCE_RESULTS[number];
  entitlementIdentifiers: string[];
  expiresAt?: number | null;
  }[];
  acquisitionVerified: boolean;
  complete: boolean;
  accessContext: string | undefined;
  expiresAt: number;
  verifiedAt: number;
  appTransactionId: string | undefined;
  providerEnvironment: "Production" | "Sandbox";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: verifyIndependentApplePaidAccess.

POST /v1/payments/apple/access/owner-evidence

Section titled “POST /v1/payments/apple/access/owner-evidence”

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Section titled “Request”

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ deviceVerificationId: string;
  providerEnvironment: "Production" | "Sandbox";
  transactionJws: string[];
  renewalInfoJws: string[];
  transactionsComplete: boolean;
  appTransactionJws?: string | undefined;
  appReceipt?: string | undefined;
  receiptVendorIdentifier?: string | undefined;
  }

Validation schemas: appleIndependentAccessRequestSchema in the downloadable schema registry.

Response

Section titled “Response”
JSON response shape 
{ version: 2;
  entitlements: EntitlementsMap;
  acquisitionEntitlements: EntitlementsMap;
  manualEntitlements: EntitlementsMap;
  transactionResults: { index: number;
  status: typeof APPLE_EVIDENCE_RESULTS[number];
  entitlementIdentifiers: string[];
  expiresAt?: number | null;
  }[];
  acquisitionVerified: boolean;
  complete: boolean;
  accessContext: string | undefined;
  expiresAt: number;
  verifiedAt: number;
  appTransactionId: string | undefined;
  providerEnvironment: "Production" | "Sandbox";
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: verifyAppleOwnerEvidence.