Update Order

Overview

The Update Order API allows merchants to modify transaction details before the customer completes payment through the SDK. This is particularly useful for dynamic checkout flows where order details may change after the initial transaction creation but before payment submission.

Use Cases

• Updating order amount after applying discounts or promotions
• Modifying shipping address information based on customer input
• Adjusting billing information before payment submission
• Updating product quantities or selections in the cart

Prerequisites

1. A transaction must already be created using the Payment Intent Creation API
2. You must implement a Custom Payment Button in your SDK integration
3. This API can only be called before the customer submits payment through the SDK

Integration Flow

API Request Parameters

POST

Name	Type	Length	Required	Signature	Description
merchantNo	String	20	Yes	Yes	Unique merchant identifier assigned by Onerway during registration.
merchantTxnId	String	64	No	Yes	Merchant-generated transaction identifier. Either merchantTxnId or transactionId must be provided to identify the transaction.
transactionId	String	20	No	Yes	Onerway-generated transaction identifier returned from the original transaction creation. Either transactionId or merchantTxnId must be provided.
orderAmount	String	19	Yes	Yes	Updated transaction amount with maximum two decimal places.
billingInformation	String		No	Yes	Updated billing details as a JSON string. See TransactionInformation for structure.
shippingInformation	String		No	Yes	Updated shipping details as a JSON string. See TransactionInformation for structure.
sign	String		Yes	No	Request signature for authentication and data integrity. See Signature documentation for generation method.

TransactionInformation

Name	Type	Length	Required	Signature	Description
firstName	String	64	No	No	First name
lastName	String	64	No	No	Last name
jpFirstName	String	64	No	No	(Japanese Katakana) First name
jpLastName	String	64	No	No	(Japanese Katakana) Last name
phone	String	32	No	No	Phone number
email	String	256	Yes	No	Email address
postalCode	String	32	No	No	Postal code
address	String	256	No	No	Address
country	String	64	Yes	No	Country. Please refer to ISO_3166.
province	String	64	Conditional	No	Province/State. Required when country is US or CA. Please refer to ISO_3166.
city	String	64	No	No	City
street	String	64	No	No	Street
number	String	64	No	No	House/Building number
identityNumber	String	64	No	No	ID number
birthDate	String	64	No	No	Birth date, format is yyyy-MM-dd

API Usage Examples

Request

{
    "merchantNo": "800209",
    "transactionId": "1919352261407277056", // transactionId from doTransaction response
    "orderAmount": "20", // Updated order amount
    "sign": "d1db1166ec3db7a8b9e8e731f22b17c7e0998702690fdfa0808378f44551d239"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919352261407277056",
        "responseTime": null,
        "txnTime": null,
        "txnTimeZone": null,
        "orderAmount": null,
        "orderCurrency": null,
        "txnAmount": null,
        "txnCurrency": null,
        "status": null,
        "redirectUrl": null,
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "e1decc2edac78b1c3ca7a842195bcf57b9d44f07c8bf8ccdeb9c21aaa60db9ee"
    }
}

Detailed Implementation

1. Create the Initial Transaction

First, create a transaction using the Payment Intent Creation API

2. Initialize SDK with Custom Payment Button

To use the Update Order API, you must initialize the SDK with a custom payment button by setting showPayButton: false in your SDK configuration. This allows you to control when to submit the payment after potential order updates.

3. Integration Workflow

The key steps for integrating the Update Order API are:

1. Detect Changes: Identify when order details need to be updated (e.g., user changes address, applies a coupon, updates quantities)

2. Prepare Parameters: Include only the parameters that need updating to avoid overwriting existing values

3. Call Update API: Send the update request to Onerway with the necessary parameters and signature

4. Verify Response: Check that the update was successful before proceeding

5. Submit Payment: When the customer is ready to complete the purchase, use the SDK's submit() method to process the payment with the updated details

4. Implementation Considerations

• Server-Side Implementation: The Update Order API should typically be called from your server rather than directly from the client for security reasons

• Signature Generation: Generate signatures according to Onerway's signature rules based on the parameters being updated

• Multiple Updates: You can update an order multiple times before payment submission if needed

• Error Handling: Implement proper error handling to manage cases where updates fail

Limitations and Considerations

1. Timing Constraints: This API can only be used before payment submission. Once payment processing begins, updates are no longer possible.

2. Partial Updates: Only include fields that need to be updated in your request. Any field included will overwrite the corresponding value in the original transaction.

3. Null Values: Never send null or empty strings as they will overwrite existing values. Omit fields that don't need updating.

4. Custom Button Requirement: This API requires implementing a custom payment button as it needs to update the transaction before payment submission.

5. Transaction Identification: You must provide either merchantTxnId or transactionId to identify the transaction to update. Using transactionId is recommended for more reliable identification.

6. Signature Generation: Remember to recalculate the signature based on the updated parameters following the standard Signature rules.

Implementation Best Practices

1. Selective Updates: Only update fields that have actually changed to minimize processing overhead.

2. Validation: Validate all updated values on your server before calling the Update Order API.

3. Error Handling: Implement robust error handling to manage update failures gracefully.

4. Order Consistency: Ensure the displayed order details in your UI match what you've updated via the API.

5. Response Verification: Always verify the API response to confirm updates were applied successfully before proceeding with payment.

6. Logging: Maintain logs of all update operations for troubleshooting and audit purposes.