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:120string 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:135oneof 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 CreateBoostReceiptCredential
message
one_time_donations.proto:59string 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:72oneof 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:152string 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:161oneof 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. The PayPal approval page presented to the user may be localized. Callers should set their language preferences via an "Accept-Language" header on the request: https://datatracker.ietf.org/doc/html/rfc3282#section-3
message
one_time_donations.proto:91string 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:104oneof 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
uint64 sepa_maximum_euros = 4
Maximum value of a one-time SEPA donation, in EUR [minor units](https://docs.stripe.com/currencies#minor-units)
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. The presented billing agreement may be localized. Callers should set their language preferences via an "Accept-Language" header on the request: https://datatracker.ietf.org/doc/html/rfc3282#section-3
message
subscriptions.proto:210bytes 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:218oneof response
result = 1
subscriber_not_found = 2
The subscriber did not exist
subscription_processor_conflict = 3
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:183bytes 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:192oneof response
result = 1
subscriber_not_found = 2
The subscriber did not exist
subscription_processor_conflict = 3
New payment processor does not match existing processor associated with the subscription
permit_rejected = 4
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:133bytes subscriberId = 1
message
subscriptions.proto:137oneof response
success = 1
subscriber_not_found = 2
The subscriber did not exist
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. Callers should set their language preferences via an "Accept-Language" header on the request: https://datatracker.ietf.org/doc/html/rfc3282#section-3
message
subscriptions.proto:446BankTransferType bank_transfer_type = 1
message
subscriptions.proto:450string 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 a receipt credential. 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:377bytes subscriberId = 1
bytes receiptCredentialRequest = 2
message
subscriptions.proto:382oneof response
success = 1
subscriber_not_found = 2
The subscriber did not exist or it did not have an associated subscription
no_paid_invoice = 3
No invoice has been issued for this subscription OR invoice is in 'draft' or 'open' state
payment_required = 4
Invoice is in any state other than 'draft', 'open', or 'paid'; Charge failure details may be present
already_redeemed = 5
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:400bytes subscriberId = 1
message
subscriptions.proto:404oneof response
success = 1
no_subscription = 2
The subscriber exists but has no subscription with a payment processor
subscriber_not_found = 3
The subscriber did not exist
Sets the default payment method for a subscriber.
message
subscriptions.proto:236bytes subscriberId = 1
oneof request
stripe = 2
braintree = 3
sepa = 4
message
subscriptions.proto:255oneof response
success = 1
subscriber_not_found = 2
The subscriber did not exist, or the referenced setup intent was not found
payment_method_not_set_up = 3
No payment method has been created for the subscriber, or the provided payment method has not finished being set up with the processor
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 GetReceiptCredential 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 GetReceiptCredential 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:341bytes subscriberId = 1
oneof request
app_store = 2
play_billing = 3
message
subscriptions.proto:356oneof response
success = 1
subscriber_not_found = 2
The subscriber did not exist or the provided purchase identifier does not exist
subscription_processor_conflict = 3
New payment processor does not match existing processor associated with the subscription
payment_required = 4
The subscription is not in a purchase state that grants the user an entitlement
invalid_transaction = 5
The provided purchase identifier is malformed or the identified transaction is not supported for use at this endpoint
Sets the subscription level and currency for a subscriber.
message
subscriptions.proto:266bytes subscriberId = 1
uint64 level = 2
string currency = 3
string idempotencyKey = 4
message
subscriptions.proto:310oneof response
success = 1
subscriber_not_found = 2
The subscriber did not exist
subscription_processor_conflict = 3
New payment processor does not match existing processor associated with the subscription
payment_method_not_set_up = 4
No payment method has been created for the subscriber
unsupported_operation = 5
The payment processor does not support this operation
unsupported_level = 6
The requested level was invalid
unsupported_currency = 7
The requested currency was invalid
payment_requires_action = 8
The card could not be charged
invalid_level_transition = 9
Cannot transition from existing level to the requested level
invalid_idempotency_key = 10
The idempotency key was invalid or re-used with a modified request
charge_failure = 11
The payment failed; see charge failure details
Creates a subscriber record if it does not exist, otherwise refreshes its last access time. 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:117bytes subscriber_id = 1
New subscriber-ids must be a randomly-generated 32 byte byte-string.
bytes donation_permit = 2
A libsignal DonationPermit from rpc Donations.CreateDonationPermit. Not required if the subscriber already exists.
message
subscriptions.proto:125oneof response
success = 1
permit_rejected = 2
The donation permit was expired or already spent
message
one_time_donations.proto:54The SEPA Direct Debit amount exceeds the allowed maximum.
Used in:
uint64 maximum = 1
The maximum amount for a SEPA transaction in the [currency's minor unit](https://docs.stripe.com/currencies#minor-units)
message
one_time_donations.proto:48The amount is below the minimum for the currency.
Used in: , ,
uint64 minimum = 1
The minimum amount for the currency in the [currency's minor unit](https://docs.stripe.com/currencies#minor-units)
message
product_configuration.proto:40Used in:
repeated uint64 amounts = 1
Amount in the currency's minor unit. Unless otherwise noted, currencies are two-decimal: divide by 100 to get the value in the specified currency. Some currencies are [zero-decimal](https://docs.stripe.com/currencies#zero-decimal); for zero-decimal currencies no multiplication is required.
message
product_configuration.proto:82Used 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:73Configuration 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:288Meaningfully 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:136Used in:
string payment_id = 1
message
one_time_donations.proto:162Used in:
bytes receipt_credential_response = 1
message
login_purchase.proto:50Used in:
bytes receipt_credential_response = 1
message
one_time_donations.proto:105Used in:
string approval_url = 1
string payment_id = 2
message
subscriptions.proto:219Used 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:193Used in:
string clientSecret = 1
PaymentProvider paymentProvider = 2
message
product_configuration.proto:48Used in:
uint64 minimum = 1
Minimum one-time donation in the currency's minor unit
map<uint64, > one_time = 2
Map of one-time donation level IDs to suggested amounts
map<uint64, uint64> subscription = 3
Map of subscription level IDs to the amount charged in the currency's minor unit
map<uint64, uint64> backup_subscription = 4
Map of backup subscription level IDs to the amount charged in the currency's minor unit
repeated PaymentMethod supported_payment_methods = 5
message
subscriptions.proto:383Used in:
bytes receiptCredentialResponse = 1
message
subscriptions.proto:405Used 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 minor 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:62Used 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:90Configuration 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 play_option_id = 4
The play billing optionID to use to purchase a Signal Login
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:306Used in: , ,
optional charge_failure = 1
message
subscriptions.proto:240Used in:
string paymentMethodToken = 1
message
subscriptions.proto:243Used in:
string setupIntentId = 1
message
subscriptions.proto:237Used in:
string paymentMethodToken = 1
message
subscriptions.proto:342Used in:
string original_transaction_id = 1
message
subscriptions.proto:345Used in:
string purchase_token = 1
message
subscriptions.proto:357Used in:
uint64 level = 1
message
subscriptions.proto:311Used 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.