package org.signal.chat.purchase
Get desktop application:
View/edit binary Protocol Buffers messages
Service for one-time purchases of logins
Obtain a ZK receipt credential for a completed one-time login payment. The receipt credential can then be presented at registration
message
login_purchase.proto:27PaymentProvider processor = 1
The payment processor. Currently, only GOOGLE_PLAY_BILLING and APPLE_APP_STORE are supported.
string purchase_identifier = 2
The identifier of a completed purchase for a signal login within the payment provider
bytes receipt_credential_request = 3
The receipt credential request. Subsequent retries to create a login credential for the same purchase_identifier must use an identical receipt_credential_request. Callers must validate that the generated receipt credential has the following properties: - Level == 300 (The login level) - ExpirationTime % 86400 == 0 - ExpirationTime == PurchaseTime + (5 * 366 * 86400) +/- (7 * 86400)
message
login_purchase.proto:49oneof response
result = 1
payment_still_processing = 2
The purchase is still pending with the payment provider. The client may retry later.
payment_required = 3
The purchase did not complete successfully.
payment_not_found = 4
The payment provider has no purchase with the provided purchase_identifier
receipt_already_issued = 5
The purchase was already redeemed for a receipt credential, but with a different receipt credential request
Service for making one-time donation payments (boost and gift) Configuration for one-time donations can be found in ProductConfiguration.
Confirm a PayPal one-time payment
message
one_time_donations.proto:113string currency = 1
ISO 4217 currency code, case-insensitive (e.g. "usd", "EUR")
uint64 amount = 2
Amount in the currency's minor unit, must be >= 1
uint64 level = 3
Donation level.
string payer_id = 4
PayPal payer ID from the approval redirect
string payment_id = 5
PayPal payment ID (PAYID-…) from CreatePayPalBoost
string payment_token = 6
PayPal payment token (EC-…) from the approval redirect
message
one_time_donations.proto:128oneof response
result = 1
amount_below_minimum = 2
The amount is below the minimum for the currency
unsupported_currency = 3
The requested currency is not supported for PayPal
unsupported_level = 4
The requested level is not a valid one-time donation level
charge_failure = 5
The payment failed; see charge failure details
Create a Stripe payment intent and return a client secret that can be used to complete the payment. Once the payment is complete, the paymentIntentId can be used with CreateBoostReceiptCredentials
message
one_time_donations.proto:52string currency = 1
ISO 4217 currency code, case-insensitive (e.g. "usd", "EUR")
uint64 amount = 2
The amount to pay in the [currency's minor unit](https://docs.stripe.com/currencies#minor-units)
uint64 level = 3
The level for the boost payment
PaymentMethod payment_method = 4
The payment method
bytes donation_permit = 5
A donation permit retrieved from Donations.createDonationPermit
message
one_time_donations.proto:65oneof response
string client_secret = 1
A client secret that can be used to complete a stripe PaymentIntent
amount_below_minimum = 2
The amount is below the minimum for the currency
amount_above_sepa_limit = 3
The amount exceeds the maximum for SEPA Direct Debit
unsupported_currency = 4
The requested currency is not supported for the given payment method
unsupported_level = 5
The requested level is not a valid one-time donation level
permit_rejected = 6
Donation permit was invalid or already spent
invalid_amount = 7
The amount in the specified currency is not supported by the payment provider
Obtain a ZK receipt credential for a completed one-time donation payment. The receipt credential can then be used to redeem the one-time donation entitlement via Donations.RedeemReceipt
message
one_time_donations.proto:145string payment_intent_id = 1
a payment ID from the processor
bytes receipt_credential_request = 2
ZK blind-signature receipt credential request bytes
PaymentProvider processor = 3
The processor that handled the payment
message
one_time_donations.proto:154oneof response
result = 1
payment_still_processing = 2
Payment is still processing; client should retry
payment_required = 3
Payment failed
payment_not_found = 4
Payment intent not found
receipt_already_issued = 5
A receipt credential was already issued for this payment
Create a PayPal one-time payment. Once the payment is complete, call ConfirmPayPalBoost with the payment ID and token
message
one_time_donations.proto:84string currency = 1
ISO 4217 currency code, case-insensitive (e.g. "usd", "EUR")
uint64 amount = 2
Amount in the currency's minor unit (e.g. cents for USD), must be >= 1
uint64 level = 3
Donation level.
string return_url = 4
URL to redirect the user to after PayPal approval
string cancel_url = 5
URL to redirect the user to if they cancel
message
one_time_donations.proto:97oneof response
result = 1
amount_below_minimum = 2
The amount is below the minimum for the currency
unsupported_currency = 3
The requested currency is not supported for PayPal
unsupported_level = 4
The requested level is not a valid one-time donation level
Retrieve product metadata for one-time donations, subscriptions, and backups
Returns configuration for donation subscriptions, backup subscriptions, and one-time donation ( "boost" and "gift") minimum and suggested amounts. Badges are referenced by ID only; resolve those IDs to full badge details via RemoteConfiguration.GetBadges.
message
product_configuration.proto:25(message has no fields)
message
product_configuration.proto:27map<string, > currencies = 1
Map of lower-cased ISO 3 currency codes to currency-specific configuration
map<uint64, > badge_levels = 2
Map of numeric donation level IDs to level-specific badge configuration
optional backup = 3
Configuration for backup subscription options
string sepa_maximum_euros = 4
Maximum value of a one-time SEPA donation
optional login = 5
Configuration for one-time Signal Login purchases
Service for creating donation subscriptions Configuration for subscription levels can be found in ProductConfiguration.
Returns a PayPal billing agreement approval URL and token that can be used to set up PayPal as a payment method.
message
subscriptions.proto:202bytes subscriberId = 1
string returnUrl = 2
a callback URL (e.g. an in-client URL handler) for when the user approved the payment
string cancelUrl = 3
a callback URL (e.g. an in-client URL handler) for when the user did not approve the payment
message
subscriptions.proto:210oneof response
result = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
subscription_processor_conflict = 4
New payment processor does not match existing processor associated with the subscription
Returns a client secret that can be used to set up a new payment method with the payment processor.
message
subscriptions.proto:175bytes subscriber_id = 1
Only PAYMENT_METHOD_CARD, PAYMENT_METHOD_SEPA_DEBIT, and PAYMENT_METHOD_IDEAL are supported; other values will result in an INVALID_ARGUMENT error.
PaymentMethod payment_method = 2
bytes donation_permit = 3
a libsignal DonationPermit from rpc Donations.CreateDonationPermit
message
subscriptions.proto:184oneof response
result = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
subscription_processor_conflict = 4
New payment processor does not match existing processor associated with the subscription
permit_rejected = 5
The donation permit was expired or already spent
Cancels any current subscription at the end of the current subscription period. Note: Apple IAP subscriptions do not support server-side cancellation, so this method should only be called after cancelling a subscription from storekit to keep server data up to date.
message
subscriptions.proto:126bytes subscriberId = 1
message
subscriptions.proto:130oneof response
success = 1
subscriber_not_found = 2
cannot_cancel_subscription = 3
The associated subscription is not a type that can be cancelled by the server. Cancel client-side, and then retry.
Returns a localized bank mandate for the specified bank transfer type
message
subscriptions.proto:435BankTransferType bank_transfer_type = 1
message
subscriptions.proto:439string mandate = 1
Create a receipt from a valid payment invoice that can be used to obtain an entitlement This request is repeatable so long as the ReceiptCredentialRequest remains the same. Clients should use the same ReceiptCredentialRequest value until they attempt to redeem the resulting ReceiptCredentialPresentation. After this point, the ReceiptCredentialRequest MUST NOT be reused or you may not be able to redeem a valid payment invoice. Clients SHOULD retry requests at this endpoint with the same ReceiptCredentialRequest value until receiving a response. After receiving a response, clients should then compute the ReceiptCredentialPresentation and redeem it at the receipt redemption endpoint. Once the first attempt is made there, the same ReceiptCredentialRequest MUST NOT be used again to request receipt credentials. Note that you may in fact redeem TWO or more invoices for the same ReceiptCredentialRequest while retrying this operation if a later invoice gets paid while you are retrying. However, the returned receipt is always for the latest invoice, so it will have the latest expiration possible and no entitlement time will be lost. The important thing is not to reuse ReceiptCredentialRequest after you have started attempting to redeem the associated ReceiptCredentialPresentation. Then you may produce a ReceiptCredentialPresentation for a later invoice that cannot be redeemed. Clients MUST validate that the generated receipt credential's level and expiration matches their expectations.
message
subscriptions.proto:365bytes subscriberId = 1
bytes receiptCredentialRequest = 2
message
subscriptions.proto:370oneof response
success = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
no_paid_invoice = 4
No invoice has been issued for this subscription OR invoice is in 'draft' or 'open' state
payment_required = 5
Invoice is in any state other than 'draft', 'open', or 'paid'; Charge failure details may be present
already_redeemed = 6
Latest paid receipt on subscription was already redeemed for a receipt credential but with a different GetReceiptCredentialRequest
Returns information about the current subscription associated with the provided subscriberId if one exists. Although it uses [Stripe's values](https://stripe.com/docs/billing/subscriptions/overview#subscription-statuses), the status field in the response is generic, with [Braintree-specific values](https://developer.paypal.com/braintree/docs/guides/recurring-billing/overview#subscription-statuses) mapped to Stripe's. Since we don't support trials or unpaid subscriptions, the associated statuses will never be returned by the API.
message
subscriptions.proto:389bytes subscriberId = 1
message
subscriptions.proto:393oneof response
success = 1
no_subscription = 2
subscriber_not_found = 3
subscriber_id_mismatch = 4
subscriberId authentication failure
Sets the default payment method for a subscriber.
message
subscriptions.proto:228bytes subscriberId = 1
oneof request
stripe = 2
braintree = 3
sepa = 4
message
subscriptions.proto:247oneof response
success = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
payment_method_not_set_up = 4
subscription_processor_conflict = 5
Payment processor does not match existing processor associated with the subscription
Set a token that represents an IAP subscription made with App Store/Google Play Billing. To set up an App Store subscription: 1. Create a subscriber with UpdateSubscriber (you must regularly refresh this subscriber) 2. [Create a subscription](https://developer.apple.com/documentation/storekit/in-app_purchase/) with the App Store directly via StoreKit and obtain a originalTransactionId. 3. Call this RPC with the originalTransactionId 4. Obtain a receipt via GetReceiptCredentials which can then be used to obtain the entitlement Play Billing: Set a purchaseToken that represents an IAP subscription made with Google Play Billing. To set up a subscription with Google Play Billing: 1. Create a subscriber with UpdateSubscriber (you must regularly refresh this subscriber) 2. [Create a subscription](https://developer.android.com/google/play/billing/integrate) with Google Play Billing directly and obtain a purchaseToken. Do not [acknowledge](https://developer.android.com/google/play/billing/integrate#subscriptions) the purchaseToken. 3. Call this RPC with the purchaseToken 4. Obtain a receipt via GetReceiptCredentials which can then be used to obtain the entitlement After calling this method, the payment is confirmed. Callers must durably store their subscriberId before calling this method to ensure their payment is tracked. Once a purchaseToken to is posted to a subscriberId, the same subscriberId must not be used with another payment method. A different playbilling purchaseToken can be posted to the same subscriberId, in this case the subscription associated with the old purchaseToken will be cancelled.
message
subscriptions.proto:333bytes subscriberId = 1
oneof request
app_store = 2
play_billing = 3
message
subscriptions.proto:348oneof response
success = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
subscription_processor_conflict = 4
New payment processor does not match existing processor associated with the subscription
payment_required = 5
invalid_transaction = 6
Sets the subscription level and currency for a subscriber.
message
subscriptions.proto:259bytes subscriberId = 1
uint64 level = 2
string currency = 3
string idempotencyKey = 4
message
subscriptions.proto:303oneof response
success = 1
subscriber_not_found = 2
subscriber_id_mismatch = 3
subscriberId authentication failure
subscription_processor_conflict = 4
New payment processor does not match existing processor associated with the subscription
payment_method_not_set_up = 5
unsupported_operation = 6
The payment processor does not support this operation
unsupported_level = 7
The requested level was invalid
unsupported_currency = 8
The requested currency was invalid
payment_requires_action = 9
The card could not be charged
invalid_level_transition = 10
Cannot transition from existing level to the requested level
invalid_idempotency_key = 11
The idempotency key was invalid or re-used with a modified request
charge_failure = 12
The payment failed; see charge failure details
Subscribers MUST periodically hit this endpoint to update the access time on the subscription record. Subscribers SHOULD attempt to make an update call approximately every 3 days. Not accessing this endpoint for an extended period of time will result in the subscription being canceled.
message
subscriptions.proto:109bytes subscriber_id = 1
bytes donation_permit = 2
A libsignal DonationPermit from rpc Donations.CreateDonationPermit. Not required if the subscriber already exists.
message
subscriptions.proto:116oneof response
success = 1
subscriber_id_mismatch = 2
subscriberId authentication failure
permit_rejected = 3
The donation permit was expired or already spent
message
one_time_donations.proto:47The SEPA Direct Debit amount exceeds the allowed maximum.
Used in:
string maximum = 1
The maximum amount for a SEPA transaction
message
one_time_donations.proto:41The amount is below the minimum for the currency.
Used in: , ,
string minimum = 1
The minimum amount for the currency
message
product_configuration.proto:40Used in:
repeated string amounts = 1
NOTE: this is a string instead of a numeric type because it is intended for display purposes only
message
product_configuration.proto:80Used in:
map<uint64, > levels = 1
A map of numeric backup level IDs to level-specific backup configuration
uint64 free_tier_media_days = 2
The number of days of media a free tier backup user gets
message
product_configuration.proto:71Configuration for a backup level - use to present appropriate client interfaces
Used in:
uint64 storage_allowance_bytes = 1
The amount of media storage in bytes that a paying subscriber may store
string play_product_id = 2
The play billing productID associated with this backup level
uint64 media_ttl_days = 3
The duration, in days, for which your backed up media is retained on the server after you stop refreshing with a paid credential
Used in:
BANK_TRANSFER_TYPE_UNKNOWN = 0
BANK_TRANSFER_TYPE_SEPA_DEBIT = 1
message
subscriptions.proto:281Meaningfully interpreting chargeFailure response fields requires inspecting the processor field first. For Stripe, code will be one of the [codes defined here](https://stripe.com/docs/api/charges/object#charge_object-failure_code), while message [may contain a further textual description](https://stripe.com/docs/api/charges/object#charge_object-failure_message). The outcome fields are optional, but present values will directly map to Stripe [response properties](https://stripe.com/docs/api/charges/object#charge_object-outcome-network_status) For Braintree, the outcome fields will be null. The code and message will contain one of - a processor decline code (as a string) in code, and associated text in message, as defined this [table](https://developer.paypal.com/braintree/docs/reference/general/processor-responses/authorization-responses) - `gateway` in code, with a [reason](https://developer.paypal.com/braintree/articles/control-panel/transactions/gateway-rejections) in message - `code` = "unknown", message = "unknown" IAP payment processors will never include charge failure information, and detailed order information should be retrieved from the payment processor directly
Used in: , , ,
PaymentProvider processor = 1
string code = 2
See [Stripe failure codes](https://stripe.com/docs/api/charges/object#charge_object-failure_code) or [Braintree decline codes](https://developer.paypal.com/braintree/docs/reference/general/processor-responses/authorization-responses#decline-codes) depending on which processor was used
string message = 3
See [Stripe failure codes](https://stripe.com/docs/api/charges/object#charge_object-failure_code) or [Braintree decline codes](https://developer.paypal.com/braintree/docs/reference/general/processor-responses/authorization-responses#decline-codes) depending on which processor was used
optional string outcome_network_status = 4
See [Outcome Network Status](https://stripe.com/docs/api/charges/object#charge_object-outcome-network_status)
optional string outcome_reason = 5
See [Outcome Reason](https://stripe.com/docs/api/charges/object#charge_object-outcome-reason)
optional string outcome_type = 6
See [Outcome Type](https://stripe.com/docs/api/charges/object#charge_object-outcome-type)
message
one_time_donations.proto:129Used in:
string payment_id = 1
message
one_time_donations.proto:155Used in:
bytes receipt_credential_response = 1
message
login_purchase.proto:50Used in:
bytes receipt_credential_response = 1
message
one_time_donations.proto:98Used in:
string approval_url = 1
string payment_id = 2
message
subscriptions.proto:211Used in:
string approvalUrl = 1
a URL to open where the user may approve the payment
string token = 2
an opaque PayPal payment identifier to use with SetDefaultPaymentMethodRequest
message
subscriptions.proto:185Used in:
string clientSecret = 1
PaymentProvider paymentProvider = 2
message
product_configuration.proto:46Used in:
string minimum = 1
Minimum one-time donation NOTE: this is a string instead of a numeric type because it is intended for display purposes only
map<uint64, > one_time = 2
Map of one-time donation level IDs to suggested amounts
map<uint64, string> subscription = 3
Map of subscription level IDs to the amount charged
map<uint64, string> backup_subscription = 4
Map of backup subscription level IDs to the amount charged
repeated PaymentMethod supported_payment_methods = 5
message
subscriptions.proto:371Used in:
bytes receiptCredentialResponse = 1
message
subscriptions.proto:394Used in:
uint64 level = 1
The subscription level
optional uint64 billing_cycle_anchor = 2
If present, UNIX Epoch Timestamp in seconds, can be used to calculate next billing date.
uint64 end_of_current_period = 3
UNIX Epoch Timestamp in seconds, when the current subscription period ends
bool active = 4
Whether there is a currently active subscription
bool cancel_at_period_end = 5
If true, an active subscription will not auto-renew at the end of the current period
string currency = 6
A three-letter ISO 4217 currency code for currency used in the subscription
uint64 amount = 7
The amount paid for the subscription in the currency's smallest unit
SubscriptionStatus status = 8
The subscription's status, mapped to Stripe's statuses. trialing will never be returned
PaymentProvider processor = 9
The payment provider associated with the subscription
PaymentMethod payment_method = 10
The payment method associated with the subscription
bool payment_processing = 11
Whether the latest charge for the subscription is in a non-terminal state
optional charge_failure = 12
if present, contains information that may be interpreted to help the user fix a failure
message
product_configuration.proto:60Used in:
string badge_id = 1
The ID of the badge awarded at this level. Resolve to full badge details via RemoteConfiguration.GetBadges.
optional uint64 badge_duration_seconds = 2
The duration for which a badge is valid. Present only for one-time (boost, gift) badges
message
product_configuration.proto:88Configuration for one-time Signal Login purchases
Used in:
uint64 level = 1
The receipt level associated with a Signal Login purchase
string play_product_id = 2
The play billing productID associated with a Signal Login purchase
string app_store_product_id = 3
The App Store productID associated with a Signal Login purchase
Used in: , , ,
PAYMENT_METHOD_UNKNOWN = 0
PAYMENT_METHOD_CARD = 1
A credit card or debit card, including those from Apple Pay and Google Pay
PAYMENT_METHOD_SEPA_DEBIT = 2
A SEPA debit account
PAYMENT_METHOD_IDEAL = 3
An iDEAL account
PAYMENT_METHOD_PAYPAL = 4
A PayPal account
PAYMENT_METHOD_GOOGLE_PLAY_BILLING = 5
PAYMENT_METHOD_APPLE_APP_STORE = 6
Used in: , , , ,
PAYMENT_PROVIDER_UNKNOWN = 0
PAYMENT_PROVIDER_STRIPE = 1
PAYMENT_PROVIDER_BRAINTREE = 2
PAYMENT_PROVIDER_GOOGLE_PLAY_BILLING = 3
PAYMENT_PROVIDER_APPLE_APP_STORE = 4
message
subscriptions.proto:299Used in: , ,
optional charge_failure = 1
message
subscriptions.proto:232Used in:
string paymentMethodToken = 1
message
subscriptions.proto:235Used in:
string setupIntentId = 1
message
subscriptions.proto:229Used in:
string paymentMethodToken = 1
message
subscriptions.proto:334Used in:
string original_transaction_id = 1
message
subscriptions.proto:337Used in:
string purchase_token = 1
message
subscriptions.proto:349Used in:
uint64 level = 1
message
subscriptions.proto:304Used in:
uint64 level = 1
Used in:
SUBSCRIPTION_STATUS_UNKNOWN = 0
SUBSCRIPTION_STATUS_ACTIVE = 1
The subscription is in good standing and the most recent payment was successful.
SUBSCRIPTION_STATUS_INCOMPLETE = 2
Payment failed when creating the subscription, or the subscription's start date is in the future.
SUBSCRIPTION_STATUS_PAST_DUE = 3
Payment on the latest renewal failed but there are processor retries left, or payment wasn't attempted.
SUBSCRIPTION_STATUS_CANCELED = 4
The subscription has been canceled.
SUBSCRIPTION_STATUS_UNPAID = 5
The latest renewal hasn't been paid but the subscription remains in place.