Create dispute
Payments
The payments REST services allow you to initiate a payment, retrieve the payment details or perform specific actions like refunding or requesting capture of a payment. A payment is identified by its paymentId. Some payment products allow a two step approach allowing you to control when the authorization takes place separate from when the funds are actually captured.
Request
This REST service allows you to dispute transactions with a NOTIFICATION_OF_CHARGEBACK or CHARGEBACKED status. The transaction will automatically be validated to ensure its state is dispute-compatible.
PayloadCreateDisputeRequest
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
object | no | read close | |
amount | integer (12) | yes | read close |
close
DescriptionAmount in cents and always having 2 decimals
|
|||
currencyCode | string (3) | yes | read close |
close
DescriptionThree-letter ISO currency code representing the currency for the amount
|
|||
contactPerson | string (30) | yes | read close |
close
DescriptionThe name of the person on your side who can be contacted regarding this dispute.
|
|||
emailAddress | string (70) | yes | read close |
close
DescriptionThe email address of the contact person.
|
|||
replyTo | string (4000) | no | read close |
close
DescriptionThe email address to which the reply message will be sent.
|
|||
requestMessage | string (4000) | no | read close |
close
DescriptionThe message sent from you to Worldline.
|
Request example
This scenario you will probably use the most
-
AmountOfMoney amountOfMoney = new AmountOfMoney(); amountOfMoney.setAmount(1234L); amountOfMoney.setCurrencyCode("USD"); CreateDisputeRequest body = new CreateDisputeRequest(); body.setAmountOfMoney(amountOfMoney); body.setContactPerson("Wile Coyote"); body.setEmailAddress("wile.e.coyote@acmelabs.com"); body.setReplyTo("r.runner@acmelabs.com"); body.setRequestMessage("This is the message from the merchant to GlobalCollect. It is a a freeform text field."); DisputeResponse response = client.v1().merchant("merchantId").payments().dispute("paymentId", body);
Responses
Please find below an overview of the possible responses.
Response 201 - CreatedDisputeResponse
The dispute was successfully created.
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
object | no | read close | |
close
DescriptionA list containing all dispute-related information that is generated upon dispute creation.
|
|||
object | no | read close | |
close
DescriptionObject containing amount and ISO currency code attributes
|
|||
amount | integer (12) | yes | read close |
close
DescriptionAmount in cents and always having 2 decimals
|
|||
currencyCode | string (3) | yes | read close |
close
DescriptionThree-letter ISO currency code representing the currency for the amount
|
|||
contactPerson | string | no | read close |
close
DescriptionThe name of the person on your side who can be contacted regarding this dispute.
|
|||
object | no | read close | |
close
DescriptionObject containing various details related to this dispute’s creation.
|
|||
disputeCreationDate | string | no | read close |
close
DescriptionThe date and time of creation of this dispute, in yyyyMMddHHmmss format.
|
|||
disputeOriginator | string | no | read close |
close
DescriptionThe originator of this dispute, which is either Worldline or you as our client.
|
|||
userName | string | no | read close |
close
DescriptionThe user account name of the dispute creator.
|
|||
emailAddress | string | no | read close |
close
DescriptionThe email address of the contact person.
|
|||
array of object | no | read close | |
close
DescriptionAn array containing all files related to this dispute.
|
|||
object | no | read close | |
fileName | string | no | read close |
close
DescriptionThe name of the file.
|
|||
fileSize | string | no | read close |
close
DescriptionThe size of the file in bytes.
|
|||
fileType | string | no | read close |
close
DescriptionThe type of the file.
|
|||
id | string | no | read close |
close
DescriptionThe numeric identifier of the file.
|
|||
object | no | read close | |
close
DescriptionA collection of reference information related to this dispute.
|
|||
merchantOrderId | string | no | read close |
close
DescriptionThe merchant’s order ID of the transaction to which this dispute is linked.
|
|||
merchantReference | string | no | read close |
close
DescriptionYour (unique) reference for the transaction that you can use to reconcile our report files.
|
|||
paymentReference | string | no | read close |
close
DescriptionPayment Reference generated by WebCollect.
|
|||
providerId | string | no | read close |
close
DescriptionThe numerical identifier of the Service Provider (Acquirer).
|
|||
providerReference | string | no | read close |
close
DescriptionThe Service Provider’s reference.
|
|||
replyTo | string | no | read close |
close
DescriptionThe email address to which the reply message will be sent.
|
|||
requestMessage | string | no | read close |
close
DescriptionThe message sent from you to Worldline.
|
|||
responseMessage | string | no | read close |
close
DescriptionThe return message sent from the GlobalCollect platform to you.
|
|||
id | string | no | read close |
close
DescriptionThe numeric identifier of the file.
|
|||
paymentId | string | no | read close |
close
DescriptionThe ID of the payment that is being disputed.
|
|||
status | string | no | read close |
close
DescriptionThe status of the dispute in alphabetical format, e.g. CREATED, DRAFT, etc.
|
|||
object | no | read close | |
close
DescriptionThis object has the numeric representation of the current payment status, timestamp of last status change and performable action on the current payment resource.
In case of failed payments and negative scenarios, detailed error information is listed.
|
|||
isCancellable | boolean | no | read close |
close
DescriptionFlag indicating if the payment can be cancelled
|
|||
statusCategory | string | no | read close |
close
DescriptionHighlevel status of the payment, payout or refund with the following possible values:
Please see Statuses for a full overview of possible values. |
|||
statusCode | integer | no | read close |
close
DescriptionNumeric status code of the legacy API. It is returned to ease the migration from the legacy APIs to Worldline Connect. You should not write new business logic based on this property as it will be deprecated in a future version of the API. The value can also be found in the GlobalCollect Payment Console, in the Ogone BackOffice and in report files.
|
|||
statusCodeChangeDateTime | string | no | read close |
close
DescriptionDate and time of payment
Format: YYYYMMDDHH24MISS |
Response example
This scenario you will probably use the most
-
{ "disputeOutput" : { "amountOfMoney" : { "amount" : 1234, "currencyCode" : "EUR" }, "contactPerson" : "Wile E. Coyote", "creationDetails" : { "disputeCreationDate" : "20181218035202" }, "emailAddress" : "wile.e.coyote@acmelabs.com", "files" : [ ], "reference" : { "merchantOrderId" : "123456", "paymentReference" : "0", "providerId" : "1000000071", "providerReference" : "null" }, "replyTo" : "wile.e.coyote@acmelabs.com", "requestMessage" : "This is the message from the merchant to GlobalCollect" }, "id" : "821", "paymentId" : "000000170100001958950000100001", "status" : "DRAFT", "statusOutput" : { "isCancellable" : false, "statusCode" : 500, "statusCodeChangeDateTime" : "20181218035202" } }
Response 400 - Bad requestErrorResponse
The request is not in the correct format or the transaction isn’t in the correct state to allow a dispute.
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
errorId | string | yes | read close |
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
array of object | yes | read close | |
close
DescriptionList of one or more errors
|
|||
object | no | read close | |
category | string | no | read close |
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
code | string | yes | read close |
close
DescriptionError code
|
|||
httpStatusCode | integer | no | read close |
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
id | string | no | read close |
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
message | string | no | read close |
close
DescriptionHuman-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
|
|||
propertyName | string | no | read close |
close
DescriptionReturned only if the error relates to a value that was missing or incorrect.
Contains a location path to the value as a JSonata query. Some common examples:
|
|||
requestId | string | no | read close |
close
DescriptionID of the request that can be used for debugging purposes
|
Response example
This scenario you will probably use the most
-
{ "errorId" : "5c37119e95088215f272b323c7761241", "errors" : [ { "code" : "310400200", "id" : "DISPUTE_ACTION_NOT_ALLOWED_ON_TRANSACTION", "category" : "DISPUTE_SERVICE_ERROR", "message" : "Action not allowed for current state", "httpStatusCode" : 400 } ] }