PayPlus gateway guide

PayPlus fact sheet

Amounts in examples on this page are in minor units (agorot) unless noted otherwise: 11000 = 110.00 ILS.

Overview

Gateway type	`payplus`
Company	PayPlus
Region / onboarding country	Middle East: Israel (`IL`)
Default currency	ILS
Card brands	Visa, Mastercard, American Express
Payment methods	Credit card, third-party token, Apple Pay, Google Pay
Sandbox endpoint	`https://restapidev.payplus.co.il/api/v1.0`
Production endpoint	`https://restapi.payplus.co.il/api/v1.0`
3DS	Spreedly 3DS2 Global: Yes. Gateway-specific 3DS2: No

Credentials

There is a single (default) auth mode. All four fields are required.

Field	Description	Stored
`api_key`	PayPlus API key. Sent in the `api-key` header.	Credential
`secret_key`	PayPlus secret key. Sent in the `secret-key` header.	Encrypted credential
`terminal_uid`	UID of the PayPlus terminal.	Safe (shown in API responses)
`cashier_uid`	UID of the PayPlus cashier.	Safe (shown in API responses)

Adding a PayPlus gateway

Create gateway

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>payplus</gateway_type>
        <description>PayPlus sandbox</description>
        <api_key>your-api-key</api_key>
        <secret_key>your-secret-key</secret_key>
        <terminal_uid>your-terminal-uid</terminal_uid>
        <cashier_uid>your-cashier-uid</cashier_uid>
        <sandbox>true</sandbox>
      </gateway>'

RESPONSE (characteristics synchronized to current integration)

Only terminal_uid and cashier_uid are echoed back. api_key and secret_key are never returned.

<gateway>
  <token>1NG6VWMZFM8A4820WTW7ZTN4RT</token>
  <gateway_type>payplus</gateway_type>
  <name>PayPlus</name>
  <description>PayPlus sandbox</description>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <terminal_uid>your-terminal-uid</terminal_uid>
  <cashier_uid>your-cashier-uid</cashier_uid>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_partial_capture type="boolean">false</supports_partial_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>terminal_uid</name>
      <value>your-terminal-uid</value>
    </credential>
    <credential>
      <name>cashier_uid</name>
      <value>your-cashier-uid</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>customer_uid</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>credit_terms</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">true</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2026-10-07T03:23:32Z</created_at>
  <updated_at type="dateTime">2026-10-07T03:23:32Z</updated_at>
</gateway>

Create a payment method

Tokenize a credit card in Spreedly before transacting. Amounts throughout this page are in minor units (agorot): 11000 = 110.00 ILS.

REQUEST

curl -X POST https://core.spreedly.com/v1/payment_methods.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<payment_method>
        <credit_card>
          <first_name>Test</first_name>
          <last_name>Buyer</last_name>
          <number>532610******5994</number>
          <month>01</month>
          <year>2030</year>
          <verification_value>***</verification_value>
        </credit_card>
        <email>[email protected]</email>
        <retained>true</retained>
      </payment_method>'

RESPONSE (abbreviated)

<transaction>
  <token>116BGBX43R833S9Y311ZDW9TXC</token>
  <succeeded type="boolean">true</succeeded>
  <transaction_type>AddPaymentMethod</transaction_type>
  <state>succeeded</state>
  <message>Succeeded!</message>
  <payment_method>
    <token>01M4A698BDYYCJ79GW6B420DMQ</token>
    <email>[email protected]</email>
    <storage_state>retained</storage_state>
    <last_four_digits>5994</last_four_digits>
    <first_six_digits>532610</first_six_digits>
    <card_type>master</card_type>
    <first_name>Test</first_name>
    <last_name>Buyer</last_name>
    <month type="integer">1</month>
    <year type="integer">2030</year>
    <payment_method_type>credit_card</payment_method_type>
    <fingerprint>REDACTED</fingerprint>
    <number>XXXX-XXXX-XXXX-5994</number>
  </payment_method>
</transaction>

Purchase

Example credit card purchase in ILS.

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>11000</amount>
        <currency_code>ILS</currency_code>
        <order_id>ORD-1791343589</order_id>
        <description>DESC-PURCHASE-1791343589</description>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A6BYJFG5ZT8H4VH20SW6BJ</token>
  <transaction_type>Purchase</transaction_type>
  <order_id>ORD-1791343589</order_id>
  <amount type="integer">11000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>46a0dccc-da53-4b55-a0e3-85aca4b00b03</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>4969208</approval_number>
      <voucher_number>22-001-003</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Authorize

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/authorize.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>1300</amount>
        <currency_code>ILS</currency_code>
        <order_id>ORD-1791343589</order_id>
        <description>DESC-PURCHASE-1791343589</description>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A6KQWB721KSEZAP5H5K2XV</token>
  <transaction_type>Authorization</transaction_type>
  <order_id>ORD-1791343845</order_id>
  <amount type="integer">1300</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>e85dd4a7-019b-4031-97a1-6b055e5d1001</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>4969222</approval_number>
      <voucher_number>22-001-004</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Capture

Capture uses the authorization transaction token. Omit the body to capture the full authorized amount. Capture creates a new PayPlus transaction, so the capture's gateway_transaction_id differs from the authorization's.

REQUEST (full capture)

curl -X POST https://core.spreedly.com/v1/transactions/AUTHORIZATION_TOKEN/capture.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A6QNF6ZMKW04H2Q8B0SZRY</token>
  <transaction_type>Capture</transaction_type>
  <amount type="integer">1300</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>a371ce0c-7c84-4b85-aba4-3a074ba54c7c</gateway_transaction_id>
  <reference_token>01M4A6KQWB721KSEZAP5H5K2XV</reference_token>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>4969222</approval_number>
      <voucher_number>22-001-004</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Void

Void a transaction that has not yet settled. PayPlus returns cancel-transaction-success. You can void a purchase or a capture. After an authorization is voided, it can no longer be captured.

REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/TRANSACTION_TOKEN/void.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A6WEG5JCWKRJW89ZAEPWEG</token>
  <transaction_type>Void</transaction_type>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id nil="true"/>
  <reference_token>01M4A6VCBGE3WFBGA8Q7RJ5RR8</reference_token>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>cancel-transaction-success</message>
  </response>
</transaction>

Credit (Refund) and partial refund

Refunds are processed as credit transactions against a captured purchase. Pass a lower amount for a partial refund. Multiple partial refunds are supported up to the original amount. If a refund exceeds the remaining amount, PayPlus returns amount-bigger-that-original-transaction.

Full refund before settlement: in QA, a full refund of an unsettled transaction came back with cancel-transaction-success and no approval or voucher number. PayPlus cancelled the transaction instead of refunding it. Partial refunds return operation has been success with an approval and voucher number. Either way, the Spreedly Credit transaction succeeds.

REQUEST (full refund)

curl -X POST https://core.spreedly.com/v1/transactions/PURCHASE_TOKEN/credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>11000</amount>
        <currency_code>ILS</currency_code>
      </transaction>'

RESPONSE (full refund) (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A7CGT39T5YJ423TYSSMSA6</token>
  <transaction_type>Credit</transaction_type>
  <amount type="integer">11000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>7fab5028-08f6-4bd6-bb7f-43f5053627b8</gateway_transaction_id>
  <reference_token>01M4A6BYJFG5ZT8H4VH20SW6BJ</reference_token>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>cancel-transaction-success</message>
  </response>
</transaction>

Partial Refund REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/PURCHASE_TOKEN/credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>4000</amount>
        <currency_code>ILS</currency_code>
      </transaction>'

RESPONSE

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A7H3YH669XKTKH0CY8H2GS</token>
  <transaction_type>Credit</transaction_type>
  <amount type="integer">4000</amount>
  <currency_code>ILS</currency_code>
  <gateway_transaction_id>620139af-30d6-43ea-aec1-fb08c0933df1</gateway_transaction_id>
  <reference_token>01M4A7FH22YDGMWATPSRYNPGPZ</reference_token>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>4969289</approval_number>
      <voucher_number>22-001-007</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

General credit

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/general_credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>15000</amount>
        <currency_code>ILS</currency_code>
        <order_id>ORD-1791343589</order_id>
        <description>DESC-PURCHASE-1791343589</description>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A7PGX8HTSNXM309KDRXH5Z</token>
  <transaction_type>GeneralCredit</transaction_type>
  <order_id>ORD-1791344985</order_id>
  <amount type="integer">15000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>7f31bb2c-50b1-4dac-9b1b-88607b4d6279</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>4969316</approval_number>
      <voucher_number>22-001-009</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Verify

Verify sends Transactions/Check to PayPlus with 1.00 ILS (100 minor units) by default.

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/verify.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <currency_code>ILS</currency_code>
        <email>[email protected]</email>
      </transaction>'

RESPONSE

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>SyntheticVerifyTxnToken</token>
  <transaction_type>Verification</transaction_type>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>00000000-0000-0000-0000-00000000v001</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0000000</approval_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Store

Store vaults the card at PayPlus and returns a Spreedly third_party_token payment method. The third_party_token is {card_token}|{customer_uid}. If the card is already vaulted, PayPlus returns card-already-exist and Spreedly reuses the existing token, so the store still succeeds.

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/store.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4A7X4ADTNM2T71DGW1CHDC9</token>
  <transaction_type>Store</transaction_type>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>c433a9e7-cb76-404d-919d-16cea41a21415994|718475d1-f74f-4d19-a13c-937fc1e514c5</gateway_transaction_id>
  <message>Succeeded!</message>
  <payment_method>
    <token>01M4A7X5HM3W5CBF5RYQ95Z5XY</token>
    <payment_method_type>third_party_token</payment_method_type>
    <storage_state>retained</storage_state>
    <gateway_type>payplus</gateway_type>
    <third_party_token>c433a9e7-cb76-404d-919d-16cea41a21415994|718475d1-f74f-4d19-a13c-937fc1e514c5</third_party_token>
  </payment_method>
  <response>
    <success type="boolean">true</success>
    <message>card-already-exist</message>
  </response>
</transaction>

Purchase with a stored PayPlus token

Use the third_party_token payment method returned by Store. Spreedly sends use_token: true, token and customer_uid to PayPlus instead of card data. Authorize works the same way.

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>STORED_PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>5000</amount>
        <currency_code>ILS</currency_code>
        <order_id>ORD-1791343589</order_id>
      </transaction>'

RESPONSE (expected shape, synthetic values)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>SyntheticStoredPurchaseToken</token>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">5000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>00000000-0000-0000-0000-00000000s001</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0000000</approval_number>
      <voucher_number>00-000-000</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
  <payment_method>
    <payment_method_type>third_party_token</payment_method_type>
    <token>STORED_PAYMENT_METHOD_TOKEN</token>
  </payment_method>
</transaction>

Unstore

Unstore removes the PayPlus card token. Redact the payment method with remove_from_gateway.

REQUEST

curl -X PUT https://core.spreedly.com/v1/payment_methods/STORED_PAYMENT_METHOD_TOKEN/redact.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <remove_from_gateway>GATEWAY_TOKEN</remove_from_gateway>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>6SKPDFMM1G8CCA488KV2NGNEYX</token>
  <transaction_type>RedactPaymentMethod</transaction_type>
  <gateway_type>payplus</gateway_type>
  <message>Succeeded!</message>
  <payment_method>
    <token>01M4A82RNYGABXFKKXE8T48DSS</token>
    <payment_method_type>third_party_token</payment_method_type>
    <storage_state>redacted</storage_state>
    <gateway_type>payplus</gateway_type>
  </payment_method>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Supported operations

Spreedly operation	PayPlus endpoint	Notes
Purchase	`POST Transactions/Charge`	Supports 3DS Global, wallets, and installments.
Authorize	`POST Transactions/Approval`	Installments are set at authorization time. Capture has no installments field.
Capture	`POST Transactions/ChargeByTransactionUID`	Capture creates a new PayPlus transaction. Refund and void must use the capture's transaction UID, not the authorization's (Spreedly handles this). Partial capture is listed as unsupported on the fact sheet.
Void	`POST Transactions/Cancel`
Refund (credit)	`POST Transactions/RefundByTransactionUID`	Full and partial refunds.
General credit	`POST Transactions/Refund`	Unreferenced credit to a card.
Verify	`POST Transactions/Check`	Uses 1.00 (100 minor units) by default.
Store	`POST Customers/Add` + `POST Token/Add`	See Store and remove.
Remove (unstore)	`POST Token/Remove/{token}`

Unsupported: partial capture, gateway-specific (PayPlus-hosted) 3DS.

Request field mapping

Spreedly field	PayPlus field	Notes
`amount`	`amount`	Sent as a decimal in major units.
`currency_code`	`currency_code`	Defaults to ILS.
Card number / month / year / CVV	`credit_card.number`, `exp_mm`, `exp_yy`, `cvv`	The CVV is omitted for wallet payments.
`order_id`	`more_info` and `extra_info`	`extra_info` is added on purchase/authorize so the order number reaches PayPlus reports. Capture and refund send `more_info` only.
`description`	`more_info_1`
`email` + billing name	`customer.customer_name`, `customer.email`	The `customer` object is sent only when both name and email are present. Phone, address, city, and `country_ISO` are added from the billing address when available.
—	`terminal_uid`, `cashier_uid`	Taken from the gateway credentials.
—	`credit_terms`	Defaults to `1` (regular). See Installments.

Gateway-specific fields

Field	Applies to	Description
`customer_uid`	All operations	An existing PayPlus customer UID. On store, Spreedly skips `Customers/Add` and attaches the card to this customer.
`installments`	Purchase, authorize	The number of payments (2 to 6). Values above 6 are capped at 6.
`credit_terms`	Purchase, authorize	`1` = regular, `8` = installments with no cardholder interest, `6` = issuer-financed credit installments (cardholder pays interest). Any other value is rejected.

Installments

PayPlus splits the total into payments itself. Spreedly sends only payments.number, never first or remaining payment amounts.

Rules

Validation before calling PayPlus. If credit_terms is not 1, 6, or 8, the transaction fails with credit_terms must be 1, 6 or 8. Combining credit_terms: 1 with installments > 1 fails with credit_terms 1 cannot be combined with installments. Neither case reaches PayPlus.
Explicit installments. When installments > 1, Spreedly sends credit_terms: 8. If the merchant also sends credit_terms: 6, Spreedly sends 6 instead. Credit installments (6) are opt-in only.
Credit installments minimum. PayPlus requires at least 3 payments for credit_terms: 6. Spreedly passes the count through as requested and PayPlus enforces the minimum.
Explicit credit_terms with no installments. The value is sent as given, and no automatic tiering is applied.
Automatic order-value tiers apply only when neither installments nor credit_terms is sent and the currency is ILS:

Order amount (ILS)	Payments sent
≥ 400	4
≥ 300	3
≥ 200	2
< 200	1 (regular charge)

Automatic tiers are on by default. Any ILS purchase or authorization of 200.00 or more is split into installments automatically, even if the merchant didn’t ask for installments. To charge in a single payment, send credit_terms: 1 or installments: 1.

Example: installments with no interest

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>SyntheticPaymentMethodToken</payment_method_token>
        <amount>30000</amount>
        <currency_code>ILS</currency_code>
        <gateway_specific_fields>
          <payplus>
            <installments>3</installments>
          </payplus>
        </gateway_specific_fields>
      </transaction>'

Example: credit installments (issuer-financed)

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>SyntheticPaymentMethodToken</payment_method_token>
        <amount>45000</amount>
        <currency_code>ILS</currency_code>
        <gateway_specific_fields>
          <payplus>
            <credit_terms>6</credit_terms>
            <installments>3</installments>
          </payplus>
        </gateway_specific_fields>
      </transaction>'

Installment responses

Installment details come back in the gateway-specific response fields. PayPlus returns credit_terms as a word: payments for 8 and credit for 6.

RESPONSE: installments (3 payments, 300.00 ILS) (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">30000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_specific_fields>
    <payplus>
      <installments>3</installments>
    </payplus>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0000000</approval_number>
      <voucher_number>00-000-000</voucher_number>
      <credit_terms>payments</credit_terms>
      <number_of_payments>3</number_of_payments>
      <first_payment_amount>100</first_payment_amount>
      <rest_payments_amount>100</rest_payments_amount>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

RESPONSE: credit installments (3 payments, 450.00 ILS) (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">45000</amount>
  <currency_code>ILS</currency_code>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <credit_terms>credit</credit_terms>
      <number_of_payments>3</number_of_payments>
      <first_payment_amount>150</first_payment_amount>
      <rest_payments_amount>150</rest_payments_amount>
    </payplus>
  </gateway_specific_response_fields>
</transaction>

Example: automatic tier (no gateway-specific fields)

A 400.00 ILS purchase sent with no installments or credit_terms goes to PayPlus as 4 payments (credit_terms: 8).

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>40000</amount>
        <currency_code>ILS</currency_code>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">40000</amount>
  <currency_code>ILS</currency_code>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <credit_terms>payments</credit_terms>
      <number_of_payments>4</number_of_payments>
      <first_payment_amount>100</first_payment_amount>
      <rest_payments_amount>100</rest_payments_amount>
    </payplus>
  </gateway_specific_response_fields>
</transaction>

Authorize, capture and wallets with installments

Installments are fixed when you authorize. Send the gateway-specific fields on authorize.json. Capture (capture.json) takes no installment fields and charges the authorized plan.
Apple Pay and Google Pay payment methods support installments the same way. Send the same gateway-specific fields on the wallet purchase or authorize.

Validation failure

An invalid credit_terms value, or credit_terms: 1 combined with installments > 1, fails before anything is sent to PayPlus.

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>30000</amount>
        <currency_code>ILS</currency_code>
        <gateway_specific_fields>
          <payplus>
            <credit_terms>5</credit_terms>
          </payplus>
        </gateway_specific_fields>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">false</succeeded>
  <state>gateway_processing_failed</state>
  <transaction_type>Purchase</transaction_type>
  <message>credit_terms must be 1, 6 or 8</message>
  <response>
    <success type="boolean">false</success>
    <message>credit_terms must be 1, 6 or 8</message>
  </response>
</transaction>

3DS Global

PayPlus supports Spreedly 3DS2 Global (3dsecure_2_mpi_purchase, 3dsecure_2_mpi_authorize). Authentication results are passed to PayPlus in the self_secure_3ds object:

Spreedly 3DS field	PayPlus `self_secure_3ds` field
`authentication_value` (CAVV)	`cavv_ucaf`
`ecommerce_indicator` (ECI)	`eci` (zero-padded to 2 digits)
`directory_server_transaction_id`	`external_trans_uid`
`three_ds_server_trans_id` (falls back to `xid`)	`external_uid`

self_secure_3ds is sent only when both CAVV and ECI are present. Otherwise the transaction goes through as non-3DS.
It is never sent for Apple Pay or Google Pay transactions. The wallet cryptogram is used instead.
Testing note: some PayPlus sandbox cards decline whenever self_secure_3ds is present. Use the PayPlus-published sandbox approval card for 3DS tests.

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>SyntheticPaymentMethodToken</payment_method_token>
        <amount>10000</amount>
        <currency_code>ILS</currency_code>
        <three_ds_version>2.2.0</three_ds_version>
        <three_ds>
          <ecommerce_indicator>02</ecommerce_indicator>
          <authentication_value>AAABBEg0VhI0VniQEjRWAAAAAAA=</authentication_value>
          <directory_server_transaction_id>f25084f0-5b16-4c0a-ae5d-b24808a95e4b</directory_server_transaction_id>
          <three_ds_server_trans_id>8a880dc0-d2d2-4067-bcb1-b08d1690b26e</three_ds_server_trans_id>
          <authentication_response_status>Y</authentication_response_status>
          <enrolled>Y</enrolled>
        </three_ds>
      </transaction>'

3DS Global example flow

Set up a merchant profile and SCA provider once, authenticate the payment method, then pass sca_authentication_token on purchase or authorize. The examples use the Spreedly test SCA provider.

Create a merchant profile

REQUEST

curl -X POST https://core.spreedly.com/v1/merchant_profiles.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<merchant_profile>
        <description> PayPlus 3DS test</description>
        <visa>
          <acquirer_merchant_id>synthetic_visa_mid</acquirer_merchant_id>
          <merchant_name>Synthetic Merchant</merchant_name>
          <country_code>376</country_code>
          <mcc>5651</mcc>
        </visa>
        <mastercard>
          <acquirer_merchant_id>synthetic_mc_mid</acquirer_merchant_id>
          <merchant_name>Synthetic Merchant</merchant_name>
          <country_code>376</country_code>
          <mcc>5651</mcc>
        </mastercard>
      </merchant_profile>'

RESPONSE (abbreviated)

<merchant_profile>
  <token>27HN3JHPNT90BB4TBN7P4T7GY0</token>
  <description> PayPlus 3DS test</description>
  <card_networks>
    <visa>
      <acquirer_merchant_id>synthetic_visa_mid</acquirer_merchant_id>
      <mcc>5651</mcc>
      <merchant_name>Synthetic Merchant</merchant_name>
      <country_code>376</country_code>
    </visa>
    <mastercard>
      <acquirer_merchant_id>synthetic_mc_mid</acquirer_merchant_id>
      <mcc>5651</mcc>
      <merchant_name>Synthetic Merchant</merchant_name>
      <country_code>376</country_code>
    </mastercard>
  </card_networks>
</merchant_profile>

Create an SCA provider

REQUEST

curl -X POST https://core.spreedly.com/v1/sca/providers.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<sca_provider>
        <type>test</type>
        <merchant_profile_key>MERCHANT_PROFILE_TOKEN</merchant_profile_key>
        <visa>
          <acquirer_bin>400000</acquirer_bin>
          <merchant_password>synthetic</merchant_password>
          <merchant_url>https://merchant.example.com</merchant_url>
        </visa>
        <mastercard>
          <acquirer_bin>510000</acquirer_bin>
          <merchant_password>synthetic</merchant_password>
          <merchant_url>https://merchant.example.com</merchant_url>
        </mastercard>
      </sca_provider>'

RESPONSE (abbreviated)

<sca_provider>
  <token>7PE24QCJ6B8FBT7TD81QSRJE6F</token>
  <merchant_profile_key>27HN3JHPNT90BB4TBN7P4T7GY0</merchant_profile_key>
  <type>test</type>
  <sandbox type="boolean">True</sandbox>
</sca_provider>

Authenticate (frictionless)

REQUEST

curl -X POST https://core.spreedly.com/v1/sca/providers/SCA_PROVIDER_TOKEN/authenticate.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <browser_info>eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ==</browser_info>
        <test_scenario>
          <scenario>authenticated</scenario>
        </test_scenario>
      </transaction>'

Complete

The completed authentication returns authentication_value and ecommerce_indicator, which Spreedly sends to PayPlus in self_secure_3ds.

curl -X POST https://core.spreedly.com/v1/transactions/SCA_AUTHENTICATION_TOKEN/complete.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>1X1YG0G8QP9NCVF3C1C8Z6EVQE</token>
  <transaction_type>Sca::Authentication</transaction_type>
  <flow_performed>frictionless</flow_performed>
  <message>High confidence</message>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <three_ds_version>2.2.0</three_ds_version>
  <ecommerce_indicator>02</ecommerce_indicator>
  <authentication_value>MTExMTExMTExMTAwY3J5cHRvZ3I=</authentication_value>
  <directory_server_transaction_id>7340fcbb-749e-44e9-9c0c-81cefcd424c5</directory_server_transaction_id>
  <authentication_response_status>Y</authentication_response_status>
  <enrolled>true</enrolled>
  <test_scenario>
    <scenario>authenticated</scenario>
  </test_scenario>
</transaction>

Purchase with the SCA authentication token

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <sca_authentication_token>SCA_AUTHENTICATION_TOKEN</sca_authentication_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <order_id>ser2381-sca-inline-1</order_id>
        <sca_authentication_parameters>
          <test_scenario>
            <scenario>authenticated</scenario>
            <ucaf_override>AAABBEg0VhI0VniQEjRWAAAAAAA=</ucaf_override>
          </test_scenario>
        </sca_authentication_parameters>
        <browser_info>eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ==</browser_info>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M51JE3HJ8KF7B8XJKS5GPCYD</token>
  <transaction_type>Purchase</transaction_type>
  <order_id>ser2381-sca-inline-1</order_id>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>c9a0ce53-7f43-4ed9-84ac-ac988f399199</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Authenticate (challenge)

A challenge scenario returns required_action: device_fingerprint. Complete the challenge before purchasing.

REQUEST

curl -X POST https://core.spreedly.com/v1/sca/providers/SCA_PROVIDER_TOKEN/authenticate.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <browser_info>eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ==</browser_info>
        <test_scenario>
          <scenario>challenge</scenario>
        </test_scenario>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">false</succeeded>
  <token>3KZKHBWXT79EXB7KTNFQ9S4DZ7</token>
  <transaction_type>Sca::Authentication</transaction_type>
  <flow_performed>device_fingerprint</flow_performed>
  <required_action>device_fingerprint</required_action>
  <authentication_response_status>C</authentication_response_status>
  <directory_response_status>C</directory_response_status>
  <three_ds_version>2.2.0</three_ds_version>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <test_scenario>
    <scenario>challenge</scenario>
  </test_scenario>
</transaction>

Complete the challenge

Run the device_fingerprint step, and any challenge that follows, in the browser with Spreedly's 3DS2 Global front-end library. Then call POST {{base_url}}/v1/transactions/{{sca_authentication_token}}/complete.json. When the authentication succeeds (authentication_response_status: Y), use its token in the purchase below. A failed or abandoned challenge must not be sent on to purchase.

Purchase after challenge

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <sca_authentication_token>SCA_AUTHENTICATION_TOKEN</sca_authentication_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <order_id>ser2381-sca-challenge-1</order_id>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M51Y5Q0X30QFMB28GN83AJGD</token>
  <transaction_type>Purchase</transaction_type>
  <order_id>ser2381-sca-challenge-1</order_id>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>6ba62d22-240b-4f72-8006-89e9f442ec7b</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Authorize with the SCA authentication token

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/authorize.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <sca_authentication_token>SCA_AUTHENTICATION_TOKEN</sca_authentication_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <order_id>ser2381-sca-authorize-1</order_id>
        <sca_authentication_parameters>
          <test_scenario>
            <scenario>authenticated</scenario>
            <ucaf_override>AAABBEg0VhI0VniQEjRWAAAAAAA=</ucaf_override>
          </test_scenario>
        </sca_authentication_parameters>
        <browser_info>eyJ3aWR0aCI6MjEzMywiaGVpZ2h0IjoxMjAwLCJkZXB0aCI6MjQsInRpbWV6b25lIjozMDAsInVzZXJfYWdlbnQiOiJTcHJlZWRseSBBZ2VudCIsImphdmEiOmZhbHNlLCJsYW5ndWFnZSI6ImVuLVVTIiwiYnJvd3Nlcl9zaXplIjoiMDQiLCJhY2NlcHRfaGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksaW1hZ2Uvd2VicCwqLyo7cT0wLjgifQ==</browser_info>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M51ZF94KZJASXR38AG7BDMCQ</token>
  <transaction_type>Authorization</transaction_type>
  <order_id>ser2381-sca-authorize-1</order_id>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>0f607ad6-a092-4a1f-bf8c-929d3fc04435</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Apple Pay and Google Pay

Spreedly decrypts the wallet payload. PayPlus receives the DPAN in credit_card, and the cryptogram and ECI in digital_wallet (type = apple-pay or google-pay).
No CVV is sent, and self_secure_3ds is skipped.
Google Pay PAN_ONLY tokens decrypt to a regular card and are charged as a standard card transaction (no digital_wallet object).
Legacy android_pay sources map to google-pay.
Installments work with wallet payments.

Apple Pay examples

Create an Apple Pay payment method

REQUEST

curl -X POST https://core.spreedly.com/v1/payment_methods.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<payment_method>
        <apple_pay>
          <cardholder_name>Test Buyer</cardholder_name>
          <pan>532614******9844</pan>
          <exp_date>300731</exp_date>
          <cryptogram>AgAAAAAABk4DWZ4C28yUQAAAAAA=</cryptogram>
          <eci_indicator>05</eci_indicator>
          <transaction_id>synthetic-apple-pay-txn-0001</transaction_id>
        </apple_pay>
        <email>[email protected]</email>
        <retained>true</retained>
      </payment_method>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>1F3BTEYSF19GYSCBZN4HMMG175</token>
  <transaction_type>AddPaymentMethod</transaction_type>
  <state>succeeded</state>
  <message>Succeeded!</message>
  <payment_method>
    <token>01M4QKHG8BWR8XJST2TS84MW1G</token>
    <payment_method_type>apple_pay</payment_method_type>
    <last_four_digits>9844</last_four_digits>
    <first_six_digits>532614</first_six_digits>
    <card_type>master</card_type>
    <month type="integer">7</month>
    <year type="integer">2030</year>
    <full_name>Test Buyer</full_name>
  </payment_method>
</transaction>

Purchase

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>APPLE_PAY_PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>10000</amount>
        <currency_code>ILS</currency_code>
        <order_id>ORD-1791343589</order_id>
        <description>DESC-PURCHASE-1791343589</description>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4QKYZE4B7G3YBX0JTFH4KXC</token>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">10000</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>898bc4aa-ebba-4825-90c0-84dc1ce99b60</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
  <payment_method>
    <payment_method_type>apple_pay</payment_method_type>
    <token>01M4QKHG8BWR8XJST2TS84MW1G</token>
  </payment_method>
</transaction>

Refund

REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/PURCHASE_TOKEN/credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>10000</amount>
        <currency_code>ILS</currency_code>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>01M4QM62SRJ43SSGEKW922XS73</token>
  <transaction_type>Credit</transaction_type>
  <amount type="integer">10000</amount>
  <currency_code>ILS</currency_code>
  <gateway_transaction_id>f570f3df-b602-4f74-8764-4ac6e8539158</gateway_transaction_id>
  <reference_token>01M4QKYZE4B7G3YBX0JTFH4KXC</reference_token>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>cancel-transaction-success</message>
  </response>
</transaction>

Void

REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/TRANSACTION_TOKEN/void.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>01M4QMJZ2SBQC1DZNFXMETBKDC</token>
  <transaction_type>Void</transaction_type>
  <reference_token>01M4QMHQE3BS3FSQY2G98TGN9R</reference_token>
  <response>
    <success type="boolean">true</success>
    <message>cancel-transaction-success</message>
  </response>
</transaction>

Google Pay examples

Create a Google Pay payment method

REQUEST

curl -X POST https://core.spreedly.com/v1/payment_methods.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<payment_method>
        <google_pay>
          <first_name>Test</first_name>
          <last_name>Buyer</last_name>
          <auth_method>CRYPTOGRAM_3DS</auth_method>
          <payment_method>CARD</payment_method>
          <dpan>532614******9844</dpan>
          <expiration_month>7</expiration_month>
          <expiration_year>2030</expiration_year>
          <cryptogram>AgAAAAAABk4DWZ4C28yUQAAAAAA=</cryptogram>
          <eci_indicator>05</eci_indicator>
          <message_id>synthetic-google-pay-msg-0001</message_id>
        </google_pay>
        <email>[email protected]</email>
        <retained>true</retained>
      </payment_method>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>6MSDY2X2X496XB1RSGAQ1V7SB4</token>
  <transaction_type>AddPaymentMethod</transaction_type>
  <state>succeeded</state>
  <message>Succeeded!</message>
  <payment_method>
    <token>01M4QN2261KBQM3KMWMSFWXVA8</token>
    <payment_method_type>google_pay</payment_method_type>
    <google_pay_type>TOKENIZED_CARD</google_pay_type>
    <last_four_digits>9844</last_four_digits>
    <first_six_digits>532614</first_six_digits>
    <card_type>master</card_type>
    <month type="integer">7</month>
    <year type="integer">2030</year>
    <full_name>Test Buyer</full_name>
  </payment_method>
</transaction>

Purchase

REQUEST

curl -X POST https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>GOOGLE_PAY_PAYMENT_METHOD_TOKEN</payment_method_token>
        <amount>1200</amount>
        <currency_code>ILS</currency_code>
        <order_id>GP-ORD-1791343589</order_id>
        <description>DESC-PURCHASE-1791343589</description>
        <email>[email protected]</email>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>01M4QN56GQQBV6TSYHJTJY1PV6</token>
  <transaction_type>Purchase</transaction_type>
  <order_id>GP-ORD-1791795305</order_id>
  <amount type="integer">1200</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>56d70f4f-5af4-4e5a-9081-84916118d5b1</gateway_transaction_id>
  <message>Succeeded!</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
  <payment_method>
    <payment_method_type>google_pay</payment_method_type>
    <token>01M4QN2261KBQM3KMWMSFWXVA8</token>
    <google_pay_type>TOKENIZED_CARD</google_pay_type>
  </payment_method>
</transaction>

Refund

Partial refund of 10.00 of a 12.00 ILS purchase.

REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/PURCHASE_TOKEN/credit.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>1000</amount>
        <currency_code>ILS</currency_code>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>01M4QN7ZW37FQVYA1FRWFE8SYA</token>
  <transaction_type>Credit</transaction_type>
  <amount type="integer">1000</amount>
  <currency_code>ILS</currency_code>
  <gateway_transaction_id>5eac10fd-ae8d-4aaf-aa0c-5004fc11c68c</gateway_transaction_id>
  <reference_token>01M4QN56GQQBV6TSYHJTJY1PV6</reference_token>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>000</status_code>
      <approval_number>0621514D</approval_number>
      <voucher_number>22-365-77</voucher_number>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">true</success>
    <message>operation has been success</message>
  </response>
</transaction>

Void

REQUEST

curl -X POST https://core.spreedly.com/v1/transactions/TRANSACTION_TOKEN/void.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
      </transaction>'

RESPONSE (abbreviated)

<transaction>
  <succeeded type="boolean">true</succeeded>
  <token>01M4QNAH73RHW72ZQV5VZG89KP</token>
  <transaction_type>Void</transaction_type>
  <reference_token>01M4QN9PA9NDFKVXT793PJEZC7</reference_token>
  <response>
    <success type="boolean">true</success>
    <message>cancel-transaction-success</message>
  </response>
</transaction>

Store and remove (third-party vaulting)

If no customer_uid GSF is supplied, Spreedly creates a PayPlus customer with Customers/Add, using the billing name (or cardholder name), email, and phone.
Spreedly tokenizes the card with Token/Add (card number + MM/YY).
If PayPlus returns card-already-exist, Spreedly calls Token/Check/{token} and reuses the existing token and its customer UID. The store is treated as successful.
The third-party token is stored as {card_token}|{customer_uid}. Later transactions send use_token: true, token, and customer_uid.
Remove calls Token/Remove/{card_token}.

Responses and error handling

Success criteria

A transaction succeeds only when all three conditions hold: results.status = success, results.code = 0, and data.transaction.status_code = 000 (or no status code is returned, as with non-transactional calls). Any HTTP error status is a failure.

Message and error code

If status_code is anything other than 000, the message is Transaction declined with status code {status_code} and the error code is the status_code.
Otherwise the message is results.description, and the error code is results.code or the HTTP status.
Invalid JSON returns Invalid JSON response received from PayPlus.
The gateway transaction ID (authorization) is data.transaction.uid.

Gateway-specific response fields

Field	Source
`status_code`	`data.transaction.status_code`
`approval_number`	`data.transaction.approval_number`
`voucher_number`	`data.transaction.voucher_number`
`credit_terms`	`data.transaction.credit_terms`. PayPlus returns a word, not the number Spreedly sends: `regular` (1), `payments` (8) or `credit` (6).
`number_of_payments`	`data.transaction.payments.number_of_payments`
`first_payment_amount`	`data.transaction.payments.first_payment_amount`
`rest_payments_amount`	`data.transaction.payments.rest_payments_amount`

<gateway_specific_response_fields>
  <payplus>
    <status_code>000</status_code>
    <approval_number>0000000</approval_number>
    <voucher_number>00-000-000</voucher_number>
    <credit_terms>payments</credit_terms>
    <number_of_payments>3</number_of_payments>
    <first_payment_amount>100</first_payment_amount>
    <rest_payments_amount>100</rest_payments_amount>
  </payplus>
</gateway_specific_response_fields>

Failure examples

Synthetic values. The shapes follow the adapter's error handling.

Decline: PayPlus returns status_code other than 000

<transaction>
  <succeeded type="boolean">false</succeeded>
  <state>gateway_processing_failed</state>
  <transaction_type>Purchase</transaction_type>
  <amount type="integer">1300</amount>
  <currency_code>ILS</currency_code>
  <gateway_type>payplus</gateway_type>
  <gateway_transaction_id>00000000-0000-0000-0000-00000000d001</gateway_transaction_id>
  <message>Transaction declined with status code 001</message>
  <gateway_specific_response_fields>
    <payplus>
      <status_code>001</status_code>
    </payplus>
  </gateway_specific_response_fields>
  <response>
    <success type="boolean">false</success>
    <message>Transaction declined with status code 001</message>
    <error_code>001</error_code>
  </response>
</transaction>

Request error: PayPlus returns results.status: error, for example for an invalid card number

<transaction>
  <succeeded type="boolean">false</succeeded>
  <state>gateway_processing_failed</state>
  <transaction_type>Purchase</transaction_type>
  <message>credit-card-number-is-incorrect</message>
  <response>
    <success type="boolean">false</success>
    <message>credit-card-number-is-incorrect</message>
    <error_code>1</error_code>
  </response>
</transaction>

Other PayPlus error descriptions you may see: api-key-or-secret-key-invalid (bad credentials), transaction-not-found, amount-bigger-that-original-transaction (over-refund), and can-not-find-card (unstore of an unknown token).

Transcript scrubbing

These values are filtered from transcripts: api-key and secret-key headers, card number, credit_card_number, cvv, token, cavv_ucaf, and wallet cryptogram.