API Reference - Refund interface
¶ Refund
Use this interface to return money to a user. We create a refund object once a partner accepts the request. The endpoint supports partial refunds, or repayment of part of a payment. You can also call it multiple times for a single, original transaction.
Uber invoke this API server-side, therefore note that cookies are not available. Uber partners expose this API.
Important: The refund API should support idempotency, allowing Uber to retry a request multiple times while only performing the action once.
¶ Flow sequence diagram
¶ Authentication
For authentication, use RSA-SHA256 signature with your Uber payments public key. See the Signature request header for more details.
This is the sandbox public key you can use for development and testing:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnYzMrDq+EnccKtcs5gQM
uP5aDe9WzdBGyUiervrFCEXmVW+T2nsSKJJR02H84LBKPjz2ioI3L289q1Qx1gj7
gvV9VZCaKejIsdKWnM5QW/1VvARWL2diScZzp5OxKX78X8aevvts79B9cVZUiEOU
E4+TTe9qLOQvbc9SssTbdqiA+1xqU+wW7IfHm5cC5kLb+Kv3pqJ63lMTx2L1iNuO
xinwun8lpdRl2+c7LswqqpUfI7Hfk0QF/XJO01BXsDxCzxkuHoWa4SNL+gNx3M69
vc5ymlZHJNZRPLMIe4+VVRaDe0dCOUcHz3cmXCjkLKfdd3JFAG+8FU/CvE1qzyP4
pwIDAQAB
-----END PUBLIC KEY-----
If the authentication fails, you receive the response: 401 Unauthorized.
¶ Request timeout
Request timeout is set to 3000ms.
¶ Retry strategy
After you make five attempts, Uber will retry the HTTP call up to 10 times. On five attempts, Uber will not retry.
¶ Request parameters
| Name | Type | Required | Description |
id
|
String | Required | Refund ID |
original_transaction_id
|
String | Required | Original transaction id in Uber’s system |
original_merchant_reference
|
String | Required | Original transaction reference in Partner’s system |
amount
|
<Object> | Required | Amount to be refunded. Multiple partial refunds are supported. |
amount.value
|
String | Required |
Value of currency in ISO4217. The value is in E5 format, or amount * 100000. For example, 10 BRL is: {"value": 1000000, "currency": "BRL"}
|
amount.currency
|
String | Required | ISO4217 |
description
|
String | Optional | Up to 256 characters |
¶ Request headers
| Name | Type | Description |
Date
|
String | Date in GMT according to RFC7231 section 7.1.1.2 |
Digest
|
String | Cryptographic hash of request body according to RFC3230 using the SHA256 algorithm. See also RFC5843. |
Signature
|
String | RSA signature of request-target, host, date and digest headers with PKCS v1.5 Padding |
¶ Response status code
Expected response status code: 201 CREATED
¶ Response body
| Name | Type | Required | Description |
status
|
String | Required | PENDING, SUCCEEDED or FAILED
|
merchant_reference
|
String | Required | Refund reference ID in the partner’s system |
failed_reason
|
String | Optional | We use this for failed refunds only |
¶
The following is an example request for a refund initiation. In this example, you can replace https://uber.partner.com/v1/payments/refund with your own URL.
curl -X POST \
https://uber.merchant.com/v1/payments/refund \
-H 'Date: Sat, 08 Jun 2019 20:51:35 GMT' \
-H 'Digest: SHA-256=FkJ3miKx7I099a8n7q3Kmn7P8/dFS1Ebx5POQd185PM=' \
-H 'Signature: keyId="rsa-key", algorithm="rsa-sha256",
headers="(request-target) host date digest",
signature="INCLUDED_SIGNATURE"'
-H 'Content-Type: application/json' \
-d '{
"id": "46a1823d29fb4384ab03-9e07a99f0d57",
"original_transaction_id": "ZWF0c19jNTcyMjg5Mi0wOWMxLTQwNjItOTQxNC1lYjVhMTczNDdkYmI=",
"original_merchant_reference": "abcdea7e9e6bb9d6f",
"description": "Sample refund",
"amount": {
"value": 100000,
"currency": "BRL"
}
}
Example Response: Status-code: 201 CREATED
Example Response Body:
{
"status": "PENDING",
"merchant_reference": "refa7e9e6bb9d6f"
}
¶ Refund errors
| HTTP status code | Reasons for error |
| 400 |
|
| 401 |
|